☎️ 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`	`$1.50` standard number-month	Reserve a standard number for an account or agent.
`premium`	`$3.00` premium number-month	Reserve a premium or easy number.
`byok`	`$0` Supafone number rent	Use customer-owned Twilio, Telnyx, Plivo, SIP, or similar credentials.

The default strategy is default_pool. Dedicated and premium numbers are real phone-number purchases or reservations and should require explicit user/admin confirmation in product UI and automation.

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 dedicated standard number.

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 Pro watcher attached.

View raw Markdown