phone numbers

speko.phoneNumbers manages caller IDs and inbound numbers for the authenticated organization.

const numbers = await speko.phoneNumbers.list();

const imported = await speko.phoneNumbers.importSipTrunk({
  e164: '+12015550199',
  sipConnectionInstallationId: '00000000-0000-4000-8000-000000000010',
  direction: 'both',
  agentId: 'agent_123',
});

Managed number purchase is the US-number path and requires phone-number business verification plus sufficient credits. For numbers you already own, or non-US carrier paths, import a SIP trunk number and link it to an agent.

Inbound routing is controlled by direction, agentId, and dispatchMetadataTemplate. A number that allows inbound calls must have either a linked agent or a dispatch metadata template. Linked agents hydrate the call prompt, routing intent, provider preferences, and tools; organization webhook endpoints resolve separately by the linked agent. Templates add static or token-substituted metadata.

Methods

PhoneNumberRow

Pass null to update() for label, dispatchMetadataTemplate, or agentId to clear them.

Inbound forwarding

A carrier-imported number (source: 'sip_trunk') reaches its agent only after your carrier forwards inbound calls to Speko. Speko provisions the inbound SIP trunk and dispatch rule for the number at import time; the one step left is on the carrier side. When setupStatus.forwardingRequired is true, setupStatus.forwardingSipUri is the authoritative target — read it from the API or copy it from the number's page or the import dialog in the dashboard. It has the form:

sip:<E.164>@<speko-sip-host>

On the hosted Speko platform (api.speko.dev) the host is 3ik7edxlm4p.sip.livekit.cloud; a self-hosted deployment has its own. Use the full international number with the leading +; no custom headers are needed because the dialed number selects the agent. UDP or TCP on port 5060 and TLS on 5061 all work.

For example, in Twilio Programmable Voice on the hosted platform:

<Response>
  <Dial>
    <Sip>sip:+33162044473@3ik7edxlm4p.sip.livekit.cloud</Sip>
  </Dial>
</Response>

or set the same host as the origination URI of a Twilio Elastic SIP trunk.

Authentication depends on the carrier connection the number was imported with:

• Telnyx connections accept calls from Telnyx's SIP signaling addresses; no credentials are needed.
• Twilio and other connections require SIP digest credentials only when you stored a carrier username and password on the connection. Twilio sends them as <Sip username="..." password="...">. Without stored credentials, calls are matched by the dialed number alone.

Do not derive the host from a LiveKit WebSocket URL you may see elsewhere. Any *.sip.livekit.cloud name resolves, but a guessed one is answered with 404 Not Found before any session is created, so nothing appears in your workspace.

Forwarded-from number

When a carrier forwards a call, Speko attempts to normalize the original forwarding source from provider fields and SIP headers. The value is available as forwardedFromNumber in call metadata and as forwarded_from_number in pre-call webhooks.

Business verification

Managed phone-number purchases are gated by phone-number KYB.

const kyb = await speko.phoneNumbers.getKyb();

await speko.phoneNumbers.submitKyb({
  businessProfile: {
    legalName: 'Acme Inc.',
    displayName: 'Acme',
    entityType: 'Corporation',
    country: 'US',
    website: 'https://example.com',
    address: {
      street: '1 Market St',
      city: 'San Francisco',
      state: 'CA',
      postalCode: '94105',
      country: 'US',
    },
    useCase: 'Customer support calls and appointment reminders.',
    expectedUsage: '500 calls per month in the US.',
  },
  authorizedRepresentative: {
    name: 'Ava Martinez',
    title: 'Operations Lead',
    email: 'ava@example.com',
    phone: '+12015551234',
  },
  attestationAccepted: true,
});