Provisional Voice API Agents with Telnyx

Telnyx launched a Provisional Agents pattern that combines a reusable AI Assistant with runtime business instructions selected by the called phone number, enabling business-specific voice agents on a single communications platform. The Node.js example maps inbound calls to business configs, renders appointment-scheduling instructions, and starts the AI Assistant with runtime greetings and instructions. This approach allows developers to attach AI voice assistants to live calls without multi-vendor handoffs.

| 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 reference https://developers.telnyx.com/api-reference/call-commands/answer-call Start AI Assistant : POST /v2/calls/{call control id}/actions/ai assistant start - API reference https://developers.telnyx.com/api-reference/call-commands/start-ai-assistant Create 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 docs https://developers.telnyx.com/docs/api/v2/overview webhook-signing BASE ASSISTANT ID string assistant-... yes for live calls AI Assistants https://portal.telnyx.com/ /ai/assistants PORT number 5000 TELNYX CONNECTION ID string connection-id npm run call Portal https://portal.telnyx.com TELNYX FROM NUMBER string +15551111111 npm run call Numbers https://portal.telnyx.com/numbers/my-numbers TEST 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 https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/build-voice-ai-agent-nodejs/README.md - Build a voice AI agent with Telnyx Inference and Call Control route-phone-calls-to-ai-agent-nodejs https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/route-phone-calls-to-ai-agent-nodejs/README.md - Receive and answer inbound Voice API calls create-ai-assistant-nodejs https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/create-ai-assistant-nodejs/README.md - Create a reusable AI Assistant