Overview
Agent Stream is a WebSocket endpoint that lets a telephony provider point its media stream at a single URL and drive a Bananaflow agent run. The agent UUID in the URL selects the agent, and the provider path segment selects the streaming protocol. Provider-specific identifiers come from the stream protocol itself. For Cloudonix, Bananaflow reads the domain from thestart.accountSid field, then uses the matching stored telephony configuration to validate the session and issue provider API calls (hangup, transfer) during the call.
This is useful when:
- You’re integrating Bananaflow into a SIP gateway or in-house dialer that already speaks a supported provider’s streaming protocol
- You want one stable endpoint per agent rather than wiring up an inbound webhook per phone number
Endpoint
{provider} is the registered provider name, currently cloudonix. {agent_uuid} is the agent’s stable UUID (see Get the Agent UUID below).
Prerequisites
- A Bananaflow agent (workflow) – published or in draft is fine
- A Cloudonix telephony configuration in your Bananaflow organization whose
domain_idmatches theaccountSidCloudonix sends in the streamstartmessage. Bananaflow uses the bearer token from this configuration to validate the call session and to issue provider API calls (hangup, transfer).
Get the Agent UUID
The Agent UUID is the workflow’s stable identifier – it doesn’t change when versions are published. To find and copy it in the UI, see Agent UUID.Connect to the WebSocket
Path parameters
Cloudonix example
<Stream> your Cloudonix Voice Application returns when the call needs to be bridged to the Bananaflow agent:
connected and start events (Twilio-compatible framing). Bananaflow extracts streamSid, callSid, session, accountSid, from, to, context, tracks, and mediaFormat from the start event payload. It validates the session against Cloudonix using the bearer token from the stored telephony configuration matched by accountSid, then begins streaming audio.
Workflow run lifecycle
When the WebSocket is accepted, Bananaflow:- Looks up the workflow by
agent_uuidand checks that its account is active - Reads Cloudonix’s
connectedandstartmessages and validates the session with Cloudonix - Checks the account’s plan and balance (nothing is charged at this step)
- Creates a new
WorkflowRun(mode=cloudonix, nameWR-AGS-XXXXXXXX). Itscall_typecomes fromstart.context:outbound-apimakes itoutbound, any other contextinbound - Stamps the
from/tonumbers oninitial_context, storessessionascall_idongathered_context, and recordsaccountSidunder the run’sinbound_webhooklog - Shows the run under the agent’s Runs tab, sets it to
runningand starts the agent
- An inbound caller hears ringing.
- An outbound callee hears nothing: they answered their own phone, so ringing would sound like a call that never connected.
1000. An outbound call is ended the same way, with no message. If Cloudonix does not end the call, the rest of your CXML runs after the stream closes.
A stream closed with 1008, 4400 or 4408 (see below) hands the call back to your CXML: Bananaflow does not end it, so whatever follows the <Connect> runs, such as the <Pause> in the example above. After a 1011 (a server-side failure), Bananaflow may or may not have asked Cloudonix to end the call, so write the rest of your CXML for a call that is still up.
Bananaflow serves one stream per call. A second stream that sends the same start.session while the first is still open is closed with 1008, and the call stays with the first stream.
A call that never reaches the agent leaves no run.
Close codes
Security notes
- Treat the URL as a secret – the agent UUID itself authorizes the connection. Store and transmit it only over TLS, and avoid logging the raw URL in places where access is broader than your operations team.
- No bearer tokens or provider secrets are passed in the URL. Provider credentials live in the stored telephony configuration (matched by
start.accountSidfor Cloudonix) and are used server-side by Bananaflow to validate the session and issue provider API calls.