☎️ Phone Numbers#

Supafone-hosted agents support three Supafone-managed number strategies plus a BYOK carrier path.

Strategies#

Strategy	Monthly price	Behavior
`default_pool`	`$0`	Use an idle shared Supafone number for dev, demos, and early traffic.
`dedicated`	`$3.00` per number-month	Reserve a standard number in the account's isolated Twilio subaccount.
`premium`	`$3.00` per number-month	Reserve premium inventory in the same isolated Twilio subaccount.
`byok`	`$0` Supafone number rent	Use customer-owned Twilio, Telnyx, Plivo, SIP, or similar credentials.

Shared-pool numbers are temporary testing routes and cannot be permanently assigned. Dedicated and premium numbers are real carrier purchases. They require a paid Stripe entitlement before Supafone creates or reuses the customer's Twilio subaccount, purchases the number, configures webhooks, and assigns it to an agent.

Search Shared Pool or Inventory#

const results = await supafone.labs.phoneNumbers.search({
  areaCode: "415",
  limit: 3,
  numberStrategy: "default_pool"
});

bash

curl https://api.supafone.ai/api/v1/labs/phone-numbers/search \
  -X POST \
  -H "Authorization: Bearer $SUPAFONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "415",
    "limit": 3,
    "number_strategy": "default_pool"
  }'

Explicit Dedicated Purchase#

Use this only after the account has chosen a $3/month dedicated number. The SDK returns Stripe Checkout first and provisions only after that checkout is paid.

await supafone.labs.phoneNumbers.buy({
  phoneNumber: "+14155550123",
  friendlyName: "Main intake line",
  agentKey: "northline-phone",
  numberStrategy: "dedicated",
  telephony: { mode: "supafone_managed", provider: "supafone" }
});

Explicit Premium Purchase#

Use this only after the account has chosen a $3/month premium number.

await supafone.labs.phoneNumbers.buy({
  phoneNumber: "+14155550123",
  friendlyName: "Premium sales line",
  agentKey: "northline-sales",
  numberStrategy: "premium",
  premium: true,
  telephony: { mode: "supafone_managed", provider: "supafone" }
});

Assign Existing Number#

await supafone.labs.phoneNumbers.assign("num_123", {
  agentKey: "northline-intake",
  style: "inbound",
  presetKey: "general_intake_receptionist"
});

BYOK Carrier#

await supafone.labs.telephony.configure({
  mode: "byok",
  provider: "twilio",
  credentials: {
    accountSid: process.env.TWILIO_ACCOUNT_SID!,
    authToken: process.env.TWILIO_AUTH_TOKEN!,
    fromNumber: "+14155550123"
  }
});

BYOK skips Supafone number rent but still keeps the hosted agent framework, stages, tools, transcripts, recordings, account sync, and Supafone Supervisor attached.

View raw Markdown