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. Configure the Agent#

Select your agent from the Agents page. From the Details page, select the newly added Telephony Configuration from the dropdown.

3. Configure the Phone Number#

From your telephony provider's dashboard, purchase a phone number and configure it to send traffic to your agent. Configure incoming calls to make a POST request to:

https://api.voicerun.com/v1/agents/<AGENT_ID>/call?environment=<ENVIRONMENT_NAME>
  • AGENT_ID: The ID of your agent (found in the URL of the Agent Details page)
  • ENVIRONMENT_NAME: The name of your environment (all lowercase, no spaces)

4. Test Your Agent#

Call the issued number to start a conversation. View the session under the Sessions tab for the agent.

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#

Agent-initiated outbound calls (vr outbound call, and warm-transfer legs spawned via StartSessionEvent) select their provider from the agent's telephony setting:

vr update agent <name-or-id> --telephony "My Telnyx"

The from-number is chosen per call (inputParameters.fromPhoneNumber, else inherited from the parent call). Telnyx is generally permissive about outbound caller ID presentation — confirm your account's ANI policy before presenting numbers you don't own.

Notes#

  • Merging two call legs (MergeSessionEvent — warm transfers) requires both legs on the same telephony configuration; keep the inbound number and the outbound agent on one Telnyx 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. Configure the agent or phone entrypoint to use the Infobip telephony configuration.
  4. In Infobip, configure the number or calls configuration to send inbound call webhooks to:
https://api.voicerun.com/v1/agents/<AGENT_ID>/call?environment=<ENVIRONMENT_NAME>

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