Outbound hold agent that pauses AI runtime while waiting on hold

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 referenceStart AI Assistant:POST /v2/calls/{call_control_id}/actions/ai_assistant_start

-API referenceStop AI Assistant:POST /v2/calls/{call_control_id}/actions/ai_assistant_stop

-API referenceSend DTMF:POST /v2/calls/{call_control_id}/actions/send_dtmf

-API referenceTranscription Start:POST /v2/calls/{call_control_id}/actions/transcription_start

-API referenceTranscription Stop:POST /v2/calls/{call_control_id}/actions/transcription_stop

-API referenceHangup:POST /v2/calls/{call_control_id}/actions/hangup

-API reference

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.

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

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 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.

Telnyx Dial APIStart AI Assistant APISend DTMF APITranscription Start APITelnyx 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- place an outbound Call Control call.build-ivr-phone-menu-python- build a traditional DTMF IVR.ai-voice-agent-with-function-calling-python- add tool calls to an AI voice agent.