How-to guidesPhone numbers

Add a number

Import a phone number from LiveKit, Twilio, or your own SIP trunk

The Phone Numbers page has two entry points (top-right, and matching CTAs in the empty state):

Get a number

An instant Speechify-provisioned trial number - US inbound only. The fastest way to take your first call.

Import number

Bring a number from LiveKit, Twilio, or your own SIP trunk (BYOC) - each has its own form.

Every import source shares two optional fields: a Label (internal name shown in the list, e.g. Sales line) and Bind to agent (the agent that answers - leave on No agent to attach later).

From LiveKit

A LiveKit-provisioned native number. US inbound only, trial - more countries are on the LiveKit roadmap.

1

Open the LiveKit tab

Click Import number, then the LiveKit tab.

2

Enter the number

Type the phone number in E.164 format (+15551234567).

3

Set label and agent (optional)

Add a label and bind it to an agent if you like.

4

Import

Click Import number.

Import dialog with the LiveKit tab selected
Import dialog, LiveKit tab

From Twilio

Bring a number you already own on Twilio. Speechify provisions an Elastic SIP Trunk on your Twilio account and wires it to LiveKit for you.

1

Open the Twilio tab

Click Import number, then the Twilio tab.

2

Add your Twilio credentials

Paste your Account SID and Auth token from twilio.com/console.

3

Enter the number

Type the number you want to import (E.164).

4

Set label and agent, then import

Add a label / bind an agent if you like, then click Import number.

Import dialog with the Twilio tab selected
Import dialog, Twilio tab

From a SIP trunk (BYOC)

For numbers from any other carrier with SIP support.

1

Open the SIP Trunk tab

Click Import number, then the SIP Trunk tab, and enter the phone number.

2

Choose a trunk

Under SIP Trunk, either Use existing (a trunk already configured in the workspace) or Create new - name, direction (Both / Inbound / Outbound), SIP address, auth credentials, destination country, transport, and media-encryption. On an inbound-capable new trunk you can also map SIP headers onto agent variables (see below); picking an existing trunk shows the mapping it already carries.

3

Import

Click Import number.

Pass a caller’s identity through from your phone system

If your own phone system has already identified the caller before it hands the call to Speechify, pass that through on the INVITE instead of making the agent ask for it again.

Set this up when the trunk is created, either under Map a header in the console’s new-trunk form or with POST /v1/agents/sip-trunks:

1{
2  "name": "Acme PBX",
3  "provider": "byoc",
4  "direction": "both",
5  "sip_address": "pbx.acme.example.com",
6  "headers_to_attributes": {
7    "X-Customer-Id": "customer_id"
8  }
9}

Every inbound call on that trunk now exposes the X-Customer-Id header to the agent as {{system__sip_customer_id}} - usable in the agent’s prompt, and in a flow’s tool arguments:

You are Sam. This caller is already signed in as account {{system__sip_customer_id}}, so do not ask them to verify their identity again.

The variable is empty on any call that arrives without the header, so write the prompt to work either way.

Mapping rules: extension headers only (X-...), up to 8 per trunk, variable names in lowercase letters, digits and underscores, and no two headers sharing a name. The mapping applies from the moment the trunk’s first number is imported, and is set when the trunk is created - to change it, create a new trunk and import the numbers onto that.

A mapped header is only as trustworthy as the system that set it, and caller ID is not a credential: the calling number on a PSTN call can be spoofed, so treat it as a hint. Use a mapped header for identity only when your own upstream actually authenticated the caller, and keep a verification step in the call for anything high-value.

Header values reach the agent as data, never as instructions - a value worded like a command is ignored.

Release or delete a number

Open Phone numbers, click the ··· menu on the number’s row, and choose:

  • Release (Speechify-managed number) - permanently returns the number to the carrier. Can’t be undone.
  • Delete (imported number) - removes it from your workspace and unbinds its agent. You can re-import it later.

You’ll be asked to type the full number to confirm. To change the bound agent, use the same ··· menu → Change agent, then pick another agent or Unbind current agent.