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.
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.
Before setting up this integration, ensure you have:
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.
To connect your Pipecat Cloud bot to Twilio’s voice network:
Purchase a phone number from Twilio if you haven’t already. Ensure the number has voice capabilities.
Retrieve your Pipecat Cloud organization name using the pipecatcloud
CLI. This information is required when creating the TwiML configuration.
This command will output a list of organizations associated with your account. For example:
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
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.
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:
Using Twilio CLI:
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)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:
For examples of these advanced features, refer to the sample implementation on GitHub and Twilio’s Voice API documentation.