Twilio Websocket Transport

Using Twilio’s WebSocket Transport for your Pipecat Cloud agents

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

How It Works

Pipecat Cloud implements Twilio’s bidirectional Media Streams protocol. While audio streams flow through WebSockets, the call session is controlled by updating the Twilio Markup Language (TwiML) associated with each call’s unique identifier (CallSid).

When Pipecat Cloud receives an incoming WebSocket connection from Twilio, 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 TwiML. This allows your bot to leverage Twilio’s REST 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 Twilio account with voice capabilities
• A Pipecat Cloud account with a Twilio Websockets-compatible bot

A ready-to-build example of a Twilio websockets bot with complete source code is available in the pipecat-examples repo.

Twilio Setup

To connect your Pipecat Cloud bot to Twilio’s voice network:

1. Purchase a phone number from Twilio 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 TwiML 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)

3. Create a TwiML Bin with the following configuration:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://api.pipecat.daily.co/ws/twilio">
      <Parameter name="_pipecatCloudServiceHost"
         value="AGENT_NAME.ORGANIZATION_NAME"/>
    </Stream>
  </Connect>
</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 value would be: customer-support.industrious-purple-cat-12345

4. Assign the TwiML Bin to your Twilio phone number:
   • Navigate to the Phone Numbers section in your Twilio dashboard
   • Select your phone number from the list
   • In the Configure tab, under “Voice Configuration” section, find “A call comes in”
   • Set this dropdown to “TwiML Bin”
   • Select the TwiML Bin you created in step 3
   • Click Save to apply your changes

Making and Receiving Calls

Receiving Inbound Calls

To test your integration, simply dial your Twilio 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 Twilio WebSocket Integration guide for complete dial-out implementation details and examples.

Custom Data Requirements

If you need to pass custom parameters to your bot (using TwiML <Parameter> tags), you’ll need to deploy your own server.py that acts as a bridge between Twilio and Pipecat Cloud:

1. Receives Twilio webhooks and extracts custom data from the incoming call
2. Generates TwiML with your custom parameters included
3. Points to Pipecat Cloud’s WebSocket URL (wss://api.pipecat.daily.co/ws/twilio) instead of your own WebSocket endpoint
4. Passes parameters through the _pipecatCloudServiceHost parameter and additional custom parameters

This hybrid approach allows you to inject custom data while leveraging Pipecat Cloud’s managed bot infrastructure. Your server handles the webhook logic and parameter injection, while Pipecat Cloud manages the bot execution and WebSocket connection.

Example TwiML with custom parameters:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://api.pipecat.daily.co/ws/twilio">
      <Parameter name="_pipecatCloudServiceHost" value="my-agent.my-org-name"/>
      <Parameter name="user_id" value="12345"/>
      <Parameter name="session_type" value="support"/>
    </Stream>
  </Connect>
</Response>

Advanced Call Control

Your bot can control the active call by leveraging Twilio’s REST API with the CallSid 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 Twilio’s Voice API documentation.