Provisional Voice API Agents with Telnyx

name	provisional-telnyx-voice-api-agents
title	Provisional Agents with Telnyx Voice API
description	Start one reusable Telnyx AI Assistant on Telnyx Voice API calls with runtime business instructions selected by the called phone number.
language	nodejs
framework	express
telnyx_products
channel

Start one reusable Telnyx AI Assistant on Telnyx Voice API calls with runtime business instructions selected by the called phone number.

This example shows a Provisional Agents with Telnyx Voice API pattern:

base Telnyx AI Assistant + Telnyx Voice API call-time business config = business-specific voice agent

The server answers inbound Telnyx Voice API calls, waits for the call.answered

webhook, maps the called number to a business config, renders appointment-scheduling instructions, and starts the base Telnyx AI Assistant with a runtime greeting

and instructions

.

Answer Call:POST /v2/calls/{call_control_id}/actions/answer

-API referenceStart AI Assistant:POST /v2/calls/{call_control_id}/actions/ai_assistant_start

-API referenceCreate Call:POST /v2/calls

• optional outbound test helper

  caller
    |
    v
  telnyx number
    |
    v
  voice api webhook
    |
    v
  express server
    |
    +--> call.initiated -> answer call
    |
    +--> call.answered
           |
           +--> called number -> examples/number-routing.json
           +--> business config -> prompt template
           +--> ai_assistant_start with runtime instructions and greeting

Telnyx is an AI Communications Infrastructure platform that combines Voice API call control and AI Assistants on one communications platform. That lets your webhook answer a call, select context from your own application data, and attach an AI voice assistant to the same live call without handing the call across multiple vendors.

Copy .env.example

to .env

and fill in:

Variable	Type	Example	Required	Description	Where to get it
TELNYX_API_KEY
string
KEY_your_telnyx_api_key_here
yes
Telnyx API v2 key used for Voice API commands

TELNYX_PUBLIC_KEY

string

base64_public_key

Webhook signing docsBASE_ASSISTANT_ID

string

assistant-...

yes for live callsAI AssistantsPORT

number

5000

TELNYX_CONNECTION_ID

string

connection-id

npm run call

PortalTELNYX_FROM_NUMBER

string

+15551111111

npm run call

NumbersTEST_TO_NUMBER

string

+15552222222

npm run call

Prerequisite: Node.js 18 or newer.

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/provisional-telnyx-voice-api-agents-nodejs
cp .env.example .env
npm install

Create a generic Telnyx AI Assistant for appointment scheduling. Keep it business-agnostic: model, voice, tools, and stable behavior belong on the base assistant. Clinic names, hours, services, and greetings come from runtime config in this example.

Set the base assistant id in .env

:

BASE_ASSISTANT_ID=assistant-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Preview the generated Telnyx Voice API ai_assistant_start

payload without making a call:

npm run preview -- smile-dental

Try another config:

npm run preview -- northside-medical

Start the server:

npm start

Expose it publicly:

ngrok http 5000

Configure your Telnyx Voice API application webhook URL:

https://<id>.ngrok.io/webhooks/voice

Assign your Telnyx number to that Voice API application, then map the number in examples/number-routing.json

:

{
  "+15551111111": "smile-dental"
}

Call the mapped number. The expected flow is:

• Telnyx sends call.initiated

. - The server answers the call.

• Telnyx sends call.answered

. - The server maps the called number to a business config.

• The server starts the base Telnyx AI Assistant with runtime instructions and greeting.

Telnyx Voice API outbound testing is useful when you want to force a business config using client_state

instead of number routing:

npm run call -- smile-dental

The Telnyx Voice API outbound helper places a call and encodes:

{ "business_config": "smile-dental" }

When the Telnyx Voice API call is answered, the webhook reads that client_state

first. If there is no usable client_state

, it falls back to called-number routing.

Receives Telnyx Voice API webhooks. Telnyx calls this endpoint directly.

For local testing without Telnyx signatures, leave TELNYX_PUBLIC_KEY

unset. For production, set TELNYX_PUBLIC_KEY

so the server verifies webhook signatures.

curl http://localhost:5000/health

Response:

{
  "status": "ok",
  "webhook": "/webhooks/voice",
  "configs": ["smile-dental", "northside-medical", "brightcare-physical-therapy"]
}

Issue	Cause	Fix
Webhook returns 401 invalid signature
TELNYX_PUBLIC_KEY is set but the request is not signed by Telnyx
Use a real Telnyx webhook, or unset TELNYX_PUBLIC_KEY for local curl testing
Live call returns BASE_ASSISTANT_ID is required
No base assistant id is configured	Create a generic AI Assistant and set BASE_ASSISTANT_ID
No business config is selected	The called number is not in examples/number-routing.json
Add the called number in E.164 format
Call rings forever	Telnyx is not reaching your webhook or the call was not answered	Check the ngrok URL, Voice API application webhook URL, and number assignment
ai_assistant_start fails
The call is not answered, assistant id is invalid, or the API key lacks permissions	Confirm call.answered arrived, check BASE_ASSISTANT_ID , and verify the API key

build-voice-ai-agent-nodejs- Build a voice AI agent with Telnyx Inference and Call Controlroute-phone-calls-to-ai-agent-nodejs- Receive and answer inbound Voice API callscreate-ai-assistant-nodejs- Create a reusable AI Assistant

source & further reading

github.com — original article