Outbound hold agent that pauses AI runtime while waiting on hold

Telnyx released an outbound hold-aware AI agent that pauses its AI assistant during phone hold queues, monitors calls via transcription, and resumes with context when a representative answers. The open-source Python/FastAPI tool navigates IVRs, detects hold from events or transcript phrases, and restarts a representative-facing assistant with the original task and hold duration. This enables automated calls to businesses like insurance companies and clinics where agents spend time on hold.

| name | outbound-hold-agent | |||| |---|---|---|---|---|---| | title | Outbound Hold-Aware AI Agent | |||| | description | Call a business, navigate IVRs with a Telnyx AI Assistant, pause the assistant during hold, monitor with transcription, and resume with context when a representative answers. | |||| | language | python | |||| | framework | fastapi | |||| | telnyx products | | |||| | channel | | Build an outbound Telnyx AI voice agent that can call a business, navigate an IVR, stop the active AI Assistant during hold, monitor the call with transcription, and restart a representative-facing assistant with the original objective and approved context. This is useful for agents that call insurance companies, hotels, clinics, service providers, or any business where the agent may spend several minutes in menus and hold queues before a human answers. - Places an outbound Call Control call. - Starts an IVR navigation AI Assistant after answer. - Lets the assistant request backend-owned DTMF through /tools/send-dtmf . - Detects hold from Telnyx events, assistant tool calls, or transcript phrases. - Stops the active assistant during hold with ai assistant stop . - Starts transcription-only monitoring during hold. - Detects representative pickup from call.unhold or transcript phrases. - Starts a second AI Assistant with the original task, context, hold duration, and recent transcript. - Exposes an /tools/end-call tool for task completion. - Includes a deterministic fake company TeXML flow for repeatable testing. Dial : POST /v2/calls - API reference https://developers.telnyx.com/api-reference/call-commands/dial 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 Stop AI Assistant : POST /v2/calls/{call control id}/actions/ai assistant stop - API reference https://developers.telnyx.com/api-reference/call-commands/stop-ai-assistant Send DTMF : POST /v2/calls/{call control id}/actions/send dtmf - API reference https://developers.telnyx.com/api-reference/call-commands/send-dtmf Transcription Start : POST /v2/calls/{call control id}/actions/transcription start - API reference https://developers.telnyx.com/api-reference/call-commands/transcription-start Transcription Stop : POST /v2/calls/{call control id}/actions/transcription stop - API reference https://developers.telnyx.com/api-reference/call-commands/transcription-stop Hangup : POST /v2/calls/{call control id}/actions/hangup - API reference https://developers.telnyx.com/api-reference/call-commands/hangup-call call.answered - start the IVR assistant. call.hold - stop the assistant and enter hold monitoring. call.unhold - treat the call as representative-ready. call.transcription - detect hold and representative pickup phrases. call.hangup - mark the local session ended. php Client / workflow - POST /calls/outbound - Telnyx dials target company - call.answered - IVR AI Assistant starts - assistant calls /tools/send-dtmf for menus - hold detected - backend stops assistant - transcription-only hold monitoring - representative detected - representative AI Assistant starts with context - task completes - assistant calls /tools/end-call | Variable | Required for real calls | Description | |---|---|---| TELNYX API KEY | yes | Telnyx API key used for Voice API requests. | TELNYX CONNECTION ID | yes | Voice API / Call Control connection ID. | TELNYX FROM NUMBER | yes | Telnyx caller ID number in E.164 format. | TELNYX IVR ASSISTANT ID | yes | Assistant used for menu navigation before hold. | TELNYX REPRESENTATIVE ASSISTANT ID | yes | Assistant used after representative pickup. | PUBLIC BASE URL | yes | Public HTTPS base URL for webhooks, assistant tools, and fake company TeXML. | TELNYX PUBLIC KEY | recommended | Telnyx webhook public key for signature verification. | TRANSCRIPTION ENGINE | no | Defaults to Deepgram . | TRANSCRIPTION MODEL | no | Defaults to nova-2 . | TRANSCRIPTION LANGUAGE | no | Defaults to en . | START TRANSCRIPTION DURING IVR | no | Defaults to true so phrase detection can catch hold language during demos. | TELNYX DRY RUN | no | Defaults to true for local testing without real Telnyx API calls. | PORT | no | Local server port. Defaults to 8000 . | git clone https://github.com/team-telnyx/telnyx-code-examples.git cd telnyx-code-examples/outbound-hold-agent-python cp .env.example .env python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements.txt python app.py Keep python app.py running in this terminal. Open a second terminal in the same folder to run the curl commands. Dry-run mode is enabled by default, so this creates a local session and mock Telnyx command responses: curl -X POST http://127.0.0.1:8000/calls/outbound \ -H "Content-Type: application/json" \ -d '{ "to":"+15551234567", "objective":"book a hotel reservation for Friday night", "target company":"Willow Creek Hotel", "context":{"guest name":"Alex Morgan","party size":2} }' Simulate Telnyx answering the call by using the returned call control id : curl -X POST http://127.0.0.1:8000/webhooks/telnyx \ -H "Content-Type: application/json" \ -d '{"data":{"event type":"call.answered","payload":{"call control id":"dry-run-call-id"}}}' Simulate IVR menu navigation: curl -X POST http://127.0.0.1:8000/tools/send-dtmf \ -H "Content-Type: application/json" \ -d '{"digits":"1","reason":"reservations menu option"}' Simulate hold detection: curl -X POST http://127.0.0.1:8000/tools/hold-detected \ -H "Content-Type: application/json" \ -d '{"reason":"please hold for the next available representative","confidence":0.95}' Simulate representative pickup from transcription: curl -X POST http://127.0.0.1:8000/webhooks/telnyx \ -H "Content-Type: application/json" \ -d '{"data":{"event type":"call.transcription","payload":{"call control id":"dry-run-call-id","transcript":"thanks for holding, this is Sarah with reservations"}}}' Inspect state: curl http://127.0.0.1:8000/sessions Expose the app: ngrok http 8000 Set PUBLIC BASE URL to the HTTPS ngrok URL. Then point a Telnyx TeXML application or test number at: https://YOUR PUBLIC BASE URL/fake-company/texml The fake company answers as Willow Creek Hotel, presents a menu, accepts digit 1 , emits hold language, and then emits a representative pickup phrase. Use this before calling a real company. Configure the IVR assistant with these tools: POST https://YOUR PUBLIC BASE URL/tools/send-dtmf POST https://YOUR PUBLIC BASE URL/tools/hold-detected Configure the representative assistant with this optional tool: POST https://YOUR PUBLIC BASE URL/tools/end-call See API.md https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/outbound-hold-agent-python/API.md for local endpoints exposed by this example. - Set TELNYX DRY RUN=false . - Expose the app over public HTTPS and set PUBLIC BASE URL . - Configure your Telnyx Voice API application webhook URL to https://YOUR PUBLIC BASE URL/webhooks/telnyx . - Set TELNYX PUBLIC KEY so webhook signatures are verified. - Add authentication to local workflow endpoints and assistant tool endpoints. - Keep DTMF actions backend-owned and validate allowed digits per target company. - Replace in-memory sessions with persistent storage. - Add destination allowlists, rate limits, retries, and stuck-call alerting. - Review outbound calling, AI disclosure, recording, transcription, and retention requirements. | Issue | Cause | Fix | |---|---|---| | Curl works but no real call is placed | TELNYX DRY RUN=true | Set TELNYX DRY RUN=false after configuring Telnyx values. | | Assistant does not start | Missing assistant ID or no call.answered webhook | Check assistant IDs and webhook URL. | | DTMF tool is accepted but IVR does not move | Wrong digit or DTMF sent before menu is ready | Confirm the assistant waits for the prompt and sends a valid option. | | Representative assistant never starts | No pickup phrase was detected | Tune REPRESENTATIVE PHRASES or trigger call.unhold . | | Webhook returns 401 | Signature verification failed | Confirm TELNYX PUBLIC KEY and webhook signature headers. | Telnyx Dial API https://developers.telnyx.com/api-reference/call-commands/dial Start AI Assistant API https://developers.telnyx.com/api-reference/call-commands/start-ai-assistant Send DTMF API https://developers.telnyx.com/api-reference/call-commands/send-dtmf Transcription Start API https://developers.telnyx.com/api-reference/call-commands/transcription-start Telnyx Voice API webhooks https://developers.telnyx.com/docs/voice/programmable-voice/voice-api-webhooks Telnyx is an AI Communications Infrastructure platform that exposes outbound calling, call-control webhooks, DTMF, AI Assistants, and real-time transcription in one Voice API, so the app can control the full call lifecycle without stitching together separate providers. make-outbound-phone-call-python https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/make-outbound-phone-call-python/README.md - place an outbound Call Control call. build-ivr-phone-menu-python https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/build-ivr-phone-menu-python/README.md - build a traditional DTMF IVR. ai-voice-agent-with-function-calling-python https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/ai-voice-agent-with-function-calling-python/README.md - add tool calls to an AI voice agent.