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

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 from the bot, you can use Twilio’s API. Here are examples using both curl and the Twilio CLI:

Using curl:

curl -X POST \
"https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \
--data-urlencode "Url=$TWIML_BIN_URL" \
--data-urlencode "To=[phone]XX" \
--data-urlencode "From=[phone]XX" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Using Twilio CLI:

twilio api:core:calls:create --from="[phone]XX" --to="[phone]XX" \
 --url="$TWIML_BIN_URL"

Where:

• $TWILIO_ACCOUNT_SID and $TWILIO_AUTH_TOKEN are your Twilio credentials (found in your Twilio Console)
• $TWIML_BIN_URL is the URL of your TwiML Bin (found in the TwiML Bin details)
• The “From” number must be your Twilio phone number
• The “To” number is the destination phone number

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 on GitHub and Twilio’s Voice API documentation.