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 on our Github. Follow the steps to build and deploy the image.

​
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 from the bot, you can use Telnyx’s Call Control API. Here are examples using both curl and the Telnyx CLI: Using curl: 
curl -X POST \
"https://api.telnyx.com/v2/calls" \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "to": "+155586753XX",
  "from": "+155522232XX",
  "connection_id": "YOUR_CONNECTION_ID",
  "webhook_url": "YOUR_TEXML_APPLICATION_URL"
}'
Using Telnyx CLI: 
telnyx calls create \
  --to="+155586753XX" \
  --from="+155522232XX" \
  --connection-id="YOUR_CONNECTION_ID" \
  --webhook-url="YOUR_TEXML_APPLICATION_URL"
Where:
  • $TELNYX_API_KEY is your Telnyx API key (found in your Telnyx Console)
  • YOUR_CONNECTION_ID is your Telnyx connection ID for the phone number
  • YOUR_TEXML_APPLICATION_URL is the webhook URL of your TeXML Application
  • The “from” number must be your Telnyx phone number
  • The “to” number is the destination phone number

​
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 on GitHub and Telnyx’s Call Control API documentation.