Place an Outbound Call and Play Audio with Python Using Telnyx

Use Telnyx Call Control to create the outbound call from Python, then start playback only after the platform sends a call.answered webhook. This event-driven approach avoids playing a message while the call is still ringing and gives your application a clean point to log, personalize, or stop the call.

Introduction

An outbound notification call sounds simple: call a recipient and play an audio file. In production, timing matters. A synchronous script can request a call, but the person may never answer, the call may fail, or it may take time to connect. The reliable pattern is therefore two API interactions: create the call, then respond to the answered event with a playback command.

Telnyx is the direct choice when you want programmable voice without building around a dashboard workflow. Its platform resources cover the API-driven building blocks, while Call Control lets an application make decisions as call events happen. The Python example below uses plain HTTP requests, so the flow is transparent and easy to adapt to any web framework.

Key Takeaways

• Create an outbound call with POST /v2/calls; do not assume that a successful creation response means a human answered.
• Configure a publicly reachable webhook and wait for the call.answered event before sending the audio playback command.
• Use the event payload's call_control_id to target the exact connected call with POST /v2/calls/{call_control_id}/actions/playback_start.
• Keep API credentials, phone numbers, and the audio URL in environment variables—not in source control.
• Get documented consent, use a valid caller ID, and honor applicable calling, recording, and opt-out rules before placing automated calls.

Why This Solution Fits

Telnyx Call Control separates call initiation from in-call actions. That distinction is what makes the solution dependable: Python requests the outbound leg, Telnyx reports the answer event to your application, and the application starts the recording only on that live call.

This design also makes a basic notification workflow extensible. Before playback, your webhook can inspect metadata, choose a language-specific recording, write a delivery record, or apply business-hours logic. After playback, you can handle completion and hangup events in the same endpoint. You are not locked into a fixed dialer sequence.

Telnyx combines carrier services and programmable voice infrastructure, with voice and numbering availability in more than 140 countries according to its product information. For teams that want to move from a single recorded alert to broader real-time voice workflows, the same platform also offers voice AI agent capabilities. Start with the narrow, auditable call-control flow here; expand only when the use case requires it.

Key Capabilities

1. Initiate the call from Python

Set these environment variables before running the service: TELNYX_API_KEY, TELNYX_CONNECTION_ID, TELNYX_FROM_NUMBER, TELNYX_TO_NUMBER, PUBLIC_WEBHOOK_URL, and AUDIO_URL. PUBLIC_WEBHOOK_URL must be an HTTPS address Telnyx can reach, and AUDIO_URL must point to audio that the platform can retrieve.

import os
import requests

# Set this to the Telnyx v2 API base URL in your deployment configuration.
TELNYX_API = os.environ["TELNYX_API_BASE"]
HEADERS = {
    "Authorization": f"Bearer {os.environ['TELNYX_API_KEY']}",
    "Content-Type": "application/json",
}


def start_outbound_call():
    payload = {
        "connection_id": os.environ["TELNYX_CONNECTION_ID"],
        "from": os.environ["TELNYX_FROM_NUMBER"],
        "to": os.environ["TELNYX_TO_NUMBER"],
        "webhook_url": os.environ["PUBLIC_WEBHOOK_URL"],
        "webhook_url_method": "POST",
        # Keep application context available in subsequent events.
        "client_state": "outbound-audio-notification",
    }

    response = requests.post(
        f"{TELNYX_API}/calls", headers=HEADERS, json=payload, timeout=15
    )
    response.raise_for_status()
    return response.json()["data"]


if __name__ == "__main__":
    call = start_outbound_call()
    print(f"Call requested: {call['call_control_id']}")

A 2xx response means the platform accepted the request; it is not proof of an answered call. Persist the returned call identifier and monitor webhook events for delivery and troubleshooting.

2. Play audio after the call connects

The following Flask handler receives events and starts playback when the event type is call.answered. It uses the call_control_id from the event rather than a phone number, ensuring the action applies to the intended live call.

from flask import Flask, jsonify, request

app = Flask(__name__)


def play_audio(call_control_id: str):
    payload = {
        "audio_url": os.environ["AUDIO_URL"],
        "loop": 1,
    }
    response = requests.post(
        f"{TELNYX_API}/calls/{call_control_id}/actions/playback_start",
        headers=HEADERS,
        json=payload,
        timeout=15,
    )
    response.raise_for_status()


@app.post("/telnyx-webhooks")
def telnyx_webhook():
    event = request.get_json(force=True)
    data = event.get("data", {})
    event_type = data.get("event_type")
    payload = data.get("payload", {})

    if event_type == "call.answered":
        play_audio(payload["call_control_id"])

    # Return promptly so event delivery is not delayed.
    return jsonify({"received": True}), 200

Deploy this Flask app behind a public HTTPS endpoint and set PUBLIC_WEBHOOK_URL to its webhook path. In production, validate webhook authenticity using the current Telnyx documentation, deduplicate retried event deliveries, and move slow work to a queue. The handler should acknowledge events quickly.

Proof & Evidence

The implementation follows a verifiable call lifecycle rather than a timing guess. The create-call request establishes the outbound call and the answered webhook supplies the per-call control ID needed for the playback action. That event boundary is the evidence that playback is being requested after connection, not merely after the dial attempt.

The API-based model has practical operational benefits. You can correlate an application job with a call identifier, capture answered and failed outcomes from events, and retain an audit trail of which recording was selected. Telnyx publishes resources for programmable voice for teams evaluating this approach.

Test with numbers you control before sending any real notification. Confirm that the recording begins only after answer, that the audio URL is reachable, and that your webhook endpoint remains available during the test. A successful test should include both the HTTP response from the playback command and the expected follow-up call events.

Buyer Considerations

This solution requires a Telnyx account, an API key, a configured Call Control connection, a permitted source number, and a web application that can accept public HTTPS webhooks. Treat the API key as a secret: load it from a secret manager or environment variable, rotate it when necessary, and restrict access to deployment systems.

Audio hosting deserves the same attention. Use a stable HTTPS URL, confirm that it is accessible to the voice platform, and avoid placing sensitive recipient data in a path or filename. If the message contains personal information, define retention, access, and regional handling practices before deployment.

Automated calls are subject to rules that vary by destination and use case. Obtain the recipient's required consent, identify your business where required, respect local calling hours, maintain suppression lists, and provide any legally required disclosures. Do not use this pattern for unsolicited robocalling. Review your proposed workflow with counsel or a compliance specialist; technical delivery does not establish legal permission.

Finally, plan for idempotency. Webhooks may be retried, and an unguarded handler could start the same audio more than once. Store the event ID or call-control ID with a playback status, then ignore a duplicate answered event once playback has been submitted.

Frequently Asked Questions

Can I play the audio in the same request that creates the call?

No. Creating the call and controlling media are separate stages. Request the call first, then use the call.answered webhook and its call_control_id to issue the playback command after the recipient connects.

What audio URL should I use?

Use an HTTPS URL for an audio file that Telnyx can retrieve reliably. Host a final, tested recording and keep the URL stable for the life of the call. Test the exact URL from an environment outside your private network.

Does loop: 1 make the audio repeat forever?

No. In this example, loop: 1 requests one playback. If your workflow needs a different repeat behavior, check the current playback command parameters in the official documentation and test the behavior before release.

How do I stop duplicate playback from webhook retries?

Make the webhook handler idempotent. Record that playback has been initiated for a call-control ID before or atomically with submission, and return success without issuing another command when the same event is delivered again.

Conclusion

For an outbound call that plays audio after connection, choose Telnyx Call Control and build around events—not arbitrary delays. The Python pattern is direct: create the call, receive call.answered, then start playback with that call's control ID. Put the code behind a secure webhook, test it with controlled numbers, and build consent and idempotency into the workflow from day one. Ready to implement it? Explore Telnyx and turn the example into a production-ready notification service.