Skip to main content

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 the start.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
Agent Stream currently supports the Cloudonix provider only. Connecting with any other provider closes the WebSocket with an error. If you need Twilio, Plivo, Telnyx, Vonage, ARI, or another provider, please email hello@bananaflow.ai with your use case.

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_id matches the accountSid Cloudonix sends in the stream start message. 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

Use this URL inside the CXML <Stream> your Cloudonix Voice Application returns when the call needs to be bridged to the Bananaflow agent:
The first two messages on the socket should be Cloudonix’s standard 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:
  1. Looks up the workflow by agent_uuid and checks that its account is active
  2. Reads Cloudonix’s connected and start messages and validates the session with Cloudonix
  3. Checks the account’s plan and balance (nothing is charged at this step)
When the agent can take the call, Bananaflow:
  1. Creates a new WorkflowRun (mode=cloudonix, name WR-AGS-XXXXXXXX). Its call_type comes from start.context: outbound-api makes it outbound, any other context inbound
  2. Stamps the from/to numbers on initial_context, stores session as call_id on gathered_context, and records accountSid under the run’s inbound_webhook log
  3. Shows the run under the agent’s Runs tab, sets it to running and starts the agent
When the agent cannot take the call yet, the call waits for up to the account’s inbound wait (30 seconds by default):
  • 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.
If the agent still cannot take the call, an inbound caller hears a short message asking them to try again in a few minutes. Bananaflow then asks Cloudonix to end the call through its API, and closes the stream with 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.accountSid for Cloudonix) and are used server-side by Bananaflow to validate the session and issue provider API calls.