Native support for Telnyx’s WebSocket Transport with Pipecat Cloud allows you to connect your AI agents with Telnyx’s voice infrastructure. This integration enables your Pipecat bots to handle real phone calls using Telnyx’s WebSocket streaming.

​
How It Works

Pipecat Cloud implements Telnyx’s bidirectional Media Streaming protocol. While audio streams flow through WebSockets, the call session is controlled by updating the Telnyx Extensible Markup Language (TeXML) associated with each call’s unique identifier (call_control_id). When Pipecat Cloud receives an incoming WebSocket connection from Telnyx, it processes the connected and start messages to initialize a new bot instance. All WebSocket messages are forwarded to your bot, including any custom parameters set in your TeXML. This allows your bot to leverage Telnyx’s Call Control API for advanced call control - such as recording conversations, transferring to human agents, or implementing complex call flows.

​
Prerequisites

Before setting up this integration, ensure you have:
  • A Telnyx account with voice capabilities
  • A Pipecat Cloud account with a Telnyx WebSocket-compatible bot
A ready-to-build example of a Telnyx websockets bot with complete source code is available in the pipecat-examples repo.

​
Telnyx Setup

To connect your Pipecat Cloud bot to Telnyx’s voice network:
  1. Purchase a phone number from Telnyx if you haven’t already. Ensure the number has voice capabilities.
  2. Retrieve your Pipecat Cloud organization name using the pipecatcloud CLI. This information is required when creating the TeXML configuration. 
$ pcc organizations list
This command will output a list of organizations associated with your account. For example: 
Organization        Name
──────────────────────────────────────
Default Workspace   three-random-words-randomnumber (active)
  1. Create a TeXML Application with the following configuration:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://api.pipecat.daily.co/ws/telnyx?serviceHost=AGENT_NAME.ORGANIZATION_NAME" bidirectionalMode="rtp"></Stream>
  </Connect>
  <Pause length="40"/>
</Response>
Replace the placeholder values:
  • AGENT_NAME with your deployed bot’s name (e.g., my-first-agent)
  • ORGANIZATION_NAME with your organization name from step 2 (e.g., three-random-words-randomnumber)
For example, if your agent is named “customer-support” and your organization is “industrious-purple-cat-12345”, your serviceHost would be: customer-support.industrious-purple-cat-12345
  1. Assign the TeXML Application to your Telnyx phone number:
    • Navigate to Voice → Programmable Voice in your Telnyx dashboard
    • In the TeXML Applications tab, select the pencil icon for the TeXML Application you created in step 3
    • In the Numbers tab, select Assign numbers
    • Select the number you would like to assign the TeXML Application to
    • Click Save to apply your changes

​
Making and Receiving Calls

​
Receiving Inbound Calls

To test your integration, simply dial your Telnyx phone number from any phone. The call will connect to your Pipecat Cloud bot, which will respond according to your bot’s configuration.

​
Making Outbound Calls

To initiate outbound calls, refer to the Telnyx WebSocket Integration guide for complete dial-out implementation details and examples.

​
Custom Data Requirements

If you need to pass custom parameters to your bot beyond the standard call information (to/from numbers, call_control_id) that Telnyx automatically provides, you can pass custom data through query parameters in the WebSocket URL. For Pipecat Cloud deployment, custom data must be passed through the special body parameter, which should be base64-encoded to comply with telephony vendor requirements: Example TeXML with custom data for Pipecat Cloud: 
import base64
import json

# Your custom data
custom_data = {
    "user_id": "12345",
    "session_type": "support",
    "campaign_id": "summer_sale"
}

# Base64 encode the data
encoded_data = base64.b64encode(json.dumps(custom_data).encode()).decode()

# Generate TeXML with encoded data
xml = f"""<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://api.pipecat.daily.co/ws/telnyx?serviceHost=my-agent.my-org-name&body={encoded_data}" bidirectionalMode="rtp"></Stream>
  </Connect>
  <Pause length="40"/>
</Response>"""
Accessing custom data in your bot: 
import base64
import json
from pipecat.runner.types import RunnerArguments

async def bot(args: RunnerArguments):
    # Access the custom data from the body parameter
    if args.body:
        # Base64 decode the data
        decoded_data = base64.b64decode(args.body).decode()
        custom_data = json.loads(decoded_data)

        user_id = custom_data.get("user_id")
        session_type = custom_data.get("session_type")
        campaign_id = custom_data.get("campaign_id")

        # Use the custom data to configure your bot
        # ...
Unlike Twilio, Telnyx automatically provides caller information (to/from numbers) in the WebSocket messages, so you only need a custom server if you require additional contextual data beyond what Telnyx provides by default.

​
Advanced Call Control

Your bot can control the active call by leveraging Telnyx’s Call Control API with the call_control_id that’s automatically provided to your bot. This enables capabilities such as:
  • Recording conversations
  • Playing audio prompts
  • Gathering DTMF input (keypad presses)
  • Ending calls programmatically
For examples of these advanced features, refer to the sample implementation in the pipecat-examples repo and Telnyx’s Call Control API documentation.