docs.VoiceRun

Bring Your Own Telephony (BYOT)

Connect your own telephony provider to VoiceRun to make and receive calls using your existing numbers and carrier. We currently support Twilio, Telnyx, and Infobip.

Step-by-step#

1. Create a telephony configuration#

Go to your Organization → Configurations → Telephony and click Add Configuration.

Each provider has different requirements:

  • Twilio: Provide Account SID, API Key SID, and API Key Secret
  • Telnyx: Provide an API Key and a Connection ID (the TeXML Application outbound calls dial through — see Telnyx Configuration)
  • Infobip: Provide an API Key and, if your account uses a regional API host, a Base URL such as https://api.infobip.com

Tip: Use a Twilio Subaccount, Telnyx API Key, or Infobip API Key with minimal required permissions.

2. Create or register a phone number#

vr create phonenumber <TELEPHONY_ID> --purchase --area-code 415
vr create phonenumber <TELEPHONY_ID> --phone-number +14155551234

Use the first form to purchase through a connected provider or the second to register a number you already own.

3. Create a release and phone entrypoint#

Create the release first, then attach its ID and the phone number to an entrypoint:

vr release production
vr create entrypoint phone support-line \
  --release <RELEASE_ID> \
  --phone-number +14155551234 \
  --telephony <TELEPHONY_ID> \
  --direction both

The entrypoint owns the public phone route and can shift traffic between releases without changing the agent or environment.

4. Test the entrypoint#

Call the number for an inbound test, or originate an outbound test:

vr outbound call support-line --to +14155559876 --wait

Inspect the result with vr session info <SESSION_ID> or from the agent's Sessions tab.

Twilio Configuration#

  1. Create a Subaccount (recommended) and a Restricted API Key
  2. Numbers can be purchased and managed in your Twilio account as usual
  3. When issuing a number from VoiceRun, we will use your Twilio configuration

Required Permissions#

For managing calls, your Restricted API Key needs:

  • Voice → Calls → Create, Fetch, Update
  • Voice → Recordings → Fetch, Read

For managing phone numbers:

  • Phone Numbers → Incoming Phone Numbers → Create, Fetch, Update, Delete
  • Phone Numbers → Available Phone Numbers → Read

Telnyx Configuration#

A Telnyx configuration needs two credentials:

  • API Key — generated in the Telnyx portal under API Keys. Note that Telnyx keys inherit the permissions of the portal user who created them (there are no per-key scopes) — releasing numbers back to Telnyx requires a user with number-deletion rights.
  • Connection ID — the numeric ID of a TeXML Application on your Telnyx account. All outbound calls VoiceRun places (including warm-transfer legs) dial out through this application.

1. Create the outbound TeXML Application (one time per account)#

  1. In the Telnyx portal: Voice → TeXML Applications → Create. Name it something durable, e.g. voicerun-outbound. The voice URL is effectively a placeholder — outbound calls supply their own per-call document URL.
  2. Attach an Outbound Voice Profile in the application's outbound settings (create one under Voice → Outbound Voice Profiles first if the account has none; traffic type "conversational"). Without a profile, every outbound dial fails with Telnyx error 10010 — Connection has no Outbound Profile assigned.
  3. Copy the application's numeric ID. This is your connectionId.

Prefer a dedicated application over reusing one of the auto-created inbound apps (below) — inbound apps' lifecycle belongs to their entrypoints.

2. Create the telephony configuration#

vr create telephony -n "My Telnyx" -p telnyx --api-key <API_KEY> --connection-id <TEXML_APP_ID>

Or via the dashboard (Organization → Configurations → Telephony). To rotate or fix credentials later, use vr update telephony <name-or-id> — credential updates merge, so fields you omit are left unchanged.

3. Numbers#

  • Purchase through VoiceRun (buys on your Telnyx account): vr create phonenumber <TELEPHONY_ID> --purchase --area-code 415 -n "support-line"
  • Register a number you already own: vr create phonenumber <TELEPHONY_ID> -p +14155551234 -n "support-line"

4. Inbound routing — automatic#

Creating a phone entrypoint wires the Telnyx side for you:

vr create entrypoint phone my-agent-inbound -p +14155551234 -r <RELEASE_ID>

VoiceRun creates a TeXML Application for the entrypoint on your account (named voicerun-entrypoint-<id>), points its voice URL at the entrypoint webhook, and assigns the number to it. No portal steps. One inbound application is managed per entrypoint; the single connectionId application is used only for outbound. Any number of inbound and outbound numbers share one Telnyx configuration.

5. Outbound calls#

vr outbound call <ENTRYPOINT> uses the phone number and provider configured on the entrypoint. The destination is supplied per call; the caller ID remains the entrypoint's phoneNumber. Confirm your Telnyx account's ANI policy before presenting any number.

Notes#

  • Merging two call legs (MergeSessionEvent — warm transfers) requires both legs on the same telephony configuration.

Infobip Configuration#

Infobip uses an API-driven call flow instead of returning TwiML/TeXML from the inbound webhook. When an inbound call arrives, VoiceRun accepts the call through the Infobip Calls API, starts a WebSocket media leg, and bridges that media stream to the selected agent release.

  1. Create an Infobip API Key with Calls API access.
  2. Add an Infobip telephony configuration in VoiceRun with:
    • apiKey — your Infobip API key
    • baseUrl — optional regional Infobip API base URL; defaults to https://api.infobip.com
  3. Create a phone entrypoint that uses the Infobip telephony configuration and routes to a release.
  4. Complete any provider-side number purchasing or webhook wiring in the Infobip dashboard using the entrypoint details shown by VoiceRun.

Infobip phone number purchasing and webhook management are handled in the Infobip dashboard. VoiceRun can create, transfer, record, fetch, and hang up Infobip calls once the telephony configuration is connected.

telephonytwiliotelnyxinfobipbyot