{"slug": "route-phone-calls-to-an-ai-agent-with-the-telnyx-voice-api", "title": "Route Phone Calls to an AI Agent With the Telnyx Voice API", "summary": "Telnyx has introduced Call Control, a webhook-driven API that enables developers to route inbound phone calls to AI agents. The API provides real-time event handling and command issuance for call states, allowing integration of speech-to-text, LLM processing, and text-to-speech within the call flow. This infrastructure layer is essential for building voice AI agents that can answer, respond, and manage calls programmatically.", "body_md": "Voice AI agents are transforming customer service, sales, and support. But before an AI can talk to a caller, you need the voice infrastructure layer — a way to receive inbound phone calls, control the call flow, and respond programmatically. Without this foundation, your AI model has no way to pick up the phone.\n\nTelnyx Call Control gives you this through webhooks. When someone calls your Telnyx number, your application receives events in real time and issues commands back — answer, speak, gather input, transfer, or hang up. This is the foundation every voice AI agent runs on.\n\nTelnyx Call Control is a webhook-driven API for programmable voice. Instead of static IVR menus, your application receives HTTP events for every call state change and responds with commands.\n\nThe event loop works like this: Telnyx sends a webhook to your application, your app processes the event, your app issues a Call Control command, and Telnyx sends the next event when that command completes. This cycle repeats for the life of the call.\n\nThis event-driven pattern is what makes voice AI possible. Your app can insert AI inference — speech-to-text, LLM processing, text-to-speech — between receiving a caller's input and responding. The Call Control webhook loop gives you a hook into every moment of the conversation.\n\nThe call flow has three steps:\n\n**A customer calls your Telnyx number.** Telnyx sends a `call.initiated`\n\nwebhook to your application with the caller's number, your number, and a `call_control_id`\n\nyou'll use for all subsequent commands on this call.\n\n**Your application answers and responds.** Your webhook handler calls the `answer`\n\naction to connect the call, then `speak`\n\nto play a text-to-speech message to the caller. Each command triggers the next webhook event when it completes — `call.answered`\n\nconfirms the call connected, `call.speak.ended`\n\nconfirms the TTS finished.\n\n**The call completes.** When the TTS finishes, Telnyx sends a `call.speak.ended`\n\nevent. Your app issues `hangup`\n\nto end the call. The `call.hangup`\n\nevent confirms cleanup.\n\nOne webhook endpoint. A state machine driven by events.\n\nEverything below works with any language or framework. All you need is the ability to receive HTTP requests and make HTTP requests.\n\nWhen you receive a `call.initiated`\n\nwebhook, answer the call with:\n\n```\ncurl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/answer \\\n  -H \"Authorization: Bearer YOUR_TELNYX_API_KEY\" \\\n  -H \"Content-Type: application/json\"\n```\n\nThe `call_control_id`\n\ncomes from the `call.initiated`\n\nwebhook payload. It's the handle you use to issue every subsequent command on this call.\n\nOnce the call is connected, play a text-to-speech message:\n\n```\ncurl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/speak \\\n  -H \"Authorization: Bearer YOUR_TELNYX_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"payload\": \"Thank you for calling. Your call is important to us. Goodbye.\",\n    \"voice\": \"female\",\n    \"language_code\": \"en-US\"\n  }'\n```\n\nThe `payload`\n\nfield is the text to speak. The `voice`\n\nfield accepts `female`\n\nor `male`\n\n. The `language_code`\n\nfield controls the language and accent — `en-US`\n\n, `en-GB`\n\n, `es-ES`\n\n, and others are supported. When playback finishes, Telnyx sends a `call.speak.ended`\n\nwebhook event.\n\nWhen you're done, terminate the call:\n\n```\ncurl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/hangup \\\n  -H \"Authorization: Bearer YOUR_TELNYX_API_KEY\" \\\n  -H \"Content-Type: application/json\"\n```\n\nTelnyx sends a `call.hangup`\n\nevent to confirm the call has ended. The `hangup_reason`\n\nfield in the event payload tells you why the call terminated.\n\nTelnyx signs every webhook request with an Ed25519 signature. Your application should verify this signature before processing the event to ensure the request actually came from Telnyx. The Telnyx SDKs handle this automatically — in Python, for example, you call `client.webhooks.unwrap()`\n\nwith the raw request body and headers.\n\nThis requires the `TELNYX_PUBLIC_KEY`\n\nenvironment variable, which you can find in the [Mission Control Portal](https://portal.telnyx.com).\n\n**Webhook-driven, not poll-driven.** Every call state change arrives as an HTTP event — `call.initiated`\n\n, `call.answered`\n\n, `call.speak.ended`\n\n, `call.hangup`\n\n. Your app stays in control without polling or long-lived connections.\n\n**Full call control vocabulary.** Answer, speak, gather DTMF or speech, transfer, conference, record — one API covers the entire call lifecycle. The same webhook loop works whether you're building a simple greeting or a multi-turn AI agent.\n\n**Private network infrastructure.** Telnyx operates a private global IP network. Voice traffic doesn't traverse the public internet, reducing latency and improving call quality.\n\n**No per-minute markup games.** Telnyx pricing is straightforward. You pay for what you use without inflated per-minute fees or hidden platform surcharges.\n\nA complete working example — a Python Flask application that implements webhook signature verification, Call Control event handling, text-to-speech, and error handling — is available in the Telnyx code examples repository:\n\n**route-phone-calls-to-ai-agent-python** on GitHub\n\nThe example includes a webhook endpoint (`/webhooks/call`\n\n), a state machine that answers inbound calls and plays a TTS greeting, and proper error handling for authentication, rate limiting, and API errors. Clone it, add your credentials, and you have a running voice webhook handler.\n\nTo get started:\n\n`/webhooks/call`\n\nendpoint.`TELNYX_API_KEY`\n\nand `TELNYX_PUBLIC_KEY`\n\nenvironment variables, and run the app.Full API documentation is available at [developers.telnyx.com](https://developers.telnyx.com).", "url": "https://wpnews.pro/news/route-phone-calls-to-an-ai-agent-with-the-telnyx-voice-api", "canonical_source": "https://dev.to/harpreetseehra/route-phone-calls-to-an-ai-agent-with-the-telnyx-voice-api-11ej", "published_at": "2026-06-29 12:19:44+00:00", "updated_at": "2026-06-29 12:49:03.501966+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "ai-agents", "natural-language-processing", "ai-infrastructure"], "entities": ["Telnyx", "Telnyx Call Control", "Ed25519"], "alternates": {"html": "https://wpnews.pro/news/route-phone-calls-to-an-ai-agent-with-the-telnyx-voice-api", "markdown": "https://wpnews.pro/news/route-phone-calls-to-an-ai-agent-with-the-telnyx-voice-api.md", "text": "https://wpnews.pro/news/route-phone-calls-to-an-ai-agent-with-the-telnyx-voice-api.txt", "jsonld": "https://wpnews.pro/news/route-phone-calls-to-an-ai-agent-with-the-telnyx-voice-api.jsonld"}}