{"slug": "outbound-hold-agent-that-pauses-ai-runtime-while-waiting-on-hold", "title": "Outbound hold agent that pauses AI runtime while waiting on hold", "summary": "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.", "body_md": "| name | outbound-hold-agent | ||||\n|---|---|---|---|---|---|\n| title | Outbound Hold-Aware AI Agent | ||||\n| 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. | ||||\n| language | python | ||||\n| framework | fastapi | ||||\n| telnyx_products |\n|\n||||\n| channel |\n|\n\nBuild 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.\n\nThis 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.\n\n- Places an outbound Call Control call.\n- Starts an IVR navigation AI Assistant after answer.\n- Lets the assistant request backend-owned DTMF through\n`/tools/send-dtmf`\n\n. - Detects hold from Telnyx events, assistant tool calls, or transcript phrases.\n- Stops the active assistant during hold with\n`ai_assistant_stop`\n\n. - Starts transcription-only monitoring during hold.\n- Detects representative pickup from\n`call.unhold`\n\nor transcript phrases. - Starts a second AI Assistant with the original task, context, hold duration, and recent transcript.\n- Exposes an\n`/tools/end-call`\n\ntool for task completion. - Includes a deterministic fake company TeXML flow for repeatable testing.\n\n**Dial**:`POST /v2/calls`\n\n-[API reference](https://developers.telnyx.com/api-reference/call-commands/dial)**Start AI Assistant**:`POST /v2/calls/{call_control_id}/actions/ai_assistant_start`\n\n-[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`\n\n-[API reference](https://developers.telnyx.com/api-reference/call-commands/stop-ai-assistant)**Send DTMF**:`POST /v2/calls/{call_control_id}/actions/send_dtmf`\n\n-[API reference](https://developers.telnyx.com/api-reference/call-commands/send-dtmf)**Transcription Start**:`POST /v2/calls/{call_control_id}/actions/transcription_start`\n\n-[API reference](https://developers.telnyx.com/api-reference/call-commands/transcription-start)**Transcription Stop**:`POST /v2/calls/{call_control_id}/actions/transcription_stop`\n\n-[API reference](https://developers.telnyx.com/api-reference/call-commands/transcription-stop)**Hangup**:`POST /v2/calls/{call_control_id}/actions/hangup`\n\n-[API reference](https://developers.telnyx.com/api-reference/call-commands/hangup-call)\n\n`call.answered`\n\n- start the IVR assistant.`call.hold`\n\n- stop the assistant and enter hold monitoring.`call.unhold`\n\n- treat the call as representative-ready.`call.transcription`\n\n- detect hold and representative pickup phrases.`call.hangup`\n\n- mark the local session ended.\n\n``` php\nClient / workflow\n  -> POST /calls/outbound\n  -> Telnyx dials target company\n  -> call.answered\n  -> IVR AI Assistant starts\n  -> assistant calls /tools/send-dtmf for menus\n  -> hold detected\n  -> backend stops assistant\n  -> transcription-only hold monitoring\n  -> representative detected\n  -> representative AI Assistant starts with context\n  -> task completes\n  -> assistant calls /tools/end-call\n```\n\n| Variable | Required for real calls | Description |\n|---|---|---|\n`TELNYX_API_KEY` |\nyes | Telnyx API key used for Voice API requests. |\n`TELNYX_CONNECTION_ID` |\nyes | Voice API / Call Control connection ID. |\n`TELNYX_FROM_NUMBER` |\nyes | Telnyx caller ID number in E.164 format. |\n`TELNYX_IVR_ASSISTANT_ID` |\nyes | Assistant used for menu navigation before hold. |\n`TELNYX_REPRESENTATIVE_ASSISTANT_ID` |\nyes | Assistant used after representative pickup. |\n`PUBLIC_BASE_URL` |\nyes | Public HTTPS base URL for webhooks, assistant tools, and fake company TeXML. |\n`TELNYX_PUBLIC_KEY` |\nrecommended | Telnyx webhook public key for signature verification. |\n`TRANSCRIPTION_ENGINE` |\nno | Defaults to `Deepgram` . |\n`TRANSCRIPTION_MODEL` |\nno | Defaults to `nova-2` . |\n`TRANSCRIPTION_LANGUAGE` |\nno | Defaults to `en` . |\n`START_TRANSCRIPTION_DURING_IVR` |\nno | Defaults to `true` so phrase detection can catch hold language during demos. |\n`TELNYX_DRY_RUN` |\nno | Defaults to `true` for local testing without real Telnyx API calls. |\n`PORT` |\nno | Local server port. Defaults to `8000` . |\n\n```\ngit clone https://github.com/team-telnyx/telnyx-code-examples.git\ncd telnyx-code-examples/outbound-hold-agent-python\ncp .env.example .env\npython3 -m venv .venv\nsource .venv/bin/activate\npython -m pip install -r requirements.txt\npython app.py\n```\n\nKeep `python app.py`\n\nrunning in this terminal. Open a second terminal in the same folder to run the curl commands.\n\nDry-run mode is enabled by default, so this creates a local session and mock Telnyx command responses:\n\n```\ncurl -X POST http://127.0.0.1:8000/calls/outbound \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"to\":\"+15551234567\",\n    \"objective\":\"book a hotel reservation for Friday night\",\n    \"target_company\":\"Willow Creek Hotel\",\n    \"context\":{\"guest_name\":\"Alex Morgan\",\"party_size\":2}\n  }'\n```\n\nSimulate Telnyx answering the call by using the returned `call_control_id`\n\n:\n\n```\ncurl -X POST http://127.0.0.1:8000/webhooks/telnyx \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"data\":{\"event_type\":\"call.answered\",\"payload\":{\"call_control_id\":\"dry-run-call-id\"}}}'\n```\n\nSimulate IVR menu navigation:\n\n```\ncurl -X POST http://127.0.0.1:8000/tools/send-dtmf \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"digits\":\"1\",\"reason\":\"reservations menu option\"}'\n```\n\nSimulate hold detection:\n\n```\ncurl -X POST http://127.0.0.1:8000/tools/hold-detected \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"reason\":\"please hold for the next available representative\",\"confidence\":0.95}'\n```\n\nSimulate representative pickup from transcription:\n\n```\ncurl -X POST http://127.0.0.1:8000/webhooks/telnyx \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"data\":{\"event_type\":\"call.transcription\",\"payload\":{\"call_control_id\":\"dry-run-call-id\",\"transcript\":\"thanks for holding, this is Sarah with reservations\"}}}'\n```\n\nInspect state:\n\n```\ncurl http://127.0.0.1:8000/sessions\n```\n\nExpose the app:\n\n```\nngrok http 8000\n```\n\nSet `PUBLIC_BASE_URL`\n\nto the HTTPS ngrok URL. Then point a Telnyx TeXML application or test number at:\n\n```\nhttps://YOUR_PUBLIC_BASE_URL/fake-company/texml\n```\n\nThe fake company answers as Willow Creek Hotel, presents a menu, accepts digit `1`\n\n, emits hold language, and then emits a representative pickup phrase. Use this before calling a real company.\n\nConfigure the IVR assistant with these tools:\n\n```\nPOST https://YOUR_PUBLIC_BASE_URL/tools/send-dtmf\nPOST https://YOUR_PUBLIC_BASE_URL/tools/hold-detected\n```\n\nConfigure the representative assistant with this optional tool:\n\n```\nPOST https://YOUR_PUBLIC_BASE_URL/tools/end-call\n```\n\nSee [ 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.\n\n- Set\n`TELNYX_DRY_RUN=false`\n\n. - Expose the app over public HTTPS and set\n`PUBLIC_BASE_URL`\n\n. - Configure your Telnyx Voice API application webhook URL to\n`https://YOUR_PUBLIC_BASE_URL/webhooks/telnyx`\n\n. - Set\n`TELNYX_PUBLIC_KEY`\n\nso webhook signatures are verified. - Add authentication to local workflow endpoints and assistant tool endpoints.\n- Keep DTMF actions backend-owned and validate allowed digits per target company.\n- Replace in-memory sessions with persistent storage.\n- Add destination allowlists, rate limits, retries, and stuck-call alerting.\n- Review outbound calling, AI disclosure, recording, transcription, and retention requirements.\n\n| Issue | Cause | Fix |\n|---|---|---|\n| Curl works but no real call is placed | `TELNYX_DRY_RUN=true` |\nSet `TELNYX_DRY_RUN=false` after configuring Telnyx values. |\n| Assistant does not start | Missing assistant ID or no `call.answered` webhook |\nCheck assistant IDs and webhook URL. |\n| 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. |\n| Representative assistant never starts | No pickup phrase was detected | Tune `REPRESENTATIVE_PHRASES` or trigger `call.unhold` . |\n| Webhook returns 401 | Signature verification failed | Confirm `TELNYX_PUBLIC_KEY` and webhook signature headers. |\n\n[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)\n\nTelnyx 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.\n\n[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.", "url": "https://wpnews.pro/news/outbound-hold-agent-that-pauses-ai-runtime-while-waiting-on-hold", "canonical_source": "https://github.com/team-telnyx/telnyx-code-examples/tree/main/outbound-hold-agent-python", "published_at": "2026-06-26 15:51:26+00:00", "updated_at": "2026-06-26 16:04:45.137510+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "natural-language-processing", "developer-tools"], "entities": ["Telnyx", "FastAPI", "Python"], "alternates": {"html": "https://wpnews.pro/news/outbound-hold-agent-that-pauses-ai-runtime-while-waiting-on-hold", "markdown": "https://wpnews.pro/news/outbound-hold-agent-that-pauses-ai-runtime-while-waiting-on-hold.md", "text": "https://wpnews.pro/news/outbound-hold-agent-that-pauses-ai-runtime-while-waiting-on-hold.txt", "jsonld": "https://wpnews.pro/news/outbound-hold-agent-that-pauses-ai-runtime-while-waiting-on-hold.jsonld"}}