> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ambivertai.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Stream
> Stream audio to a Ambivert AI agent over a WebSocket
## Overview
Agent Stream is a WebSocket endpoint that lets a telephony provider point its media stream at a single URL and drive a Ambivert AI agent run. The agent UUID in the URL selects the agent; provider-specific identifiers in the query string (for Cloudonix: `Domain`) tell Ambivert AI which stored telephony configuration to use for that call. The bearer token and other credentials are never passed in the URL — they live in the stored configuration and are used by Ambivert AI to validate the session and to issue provider API calls (hangup, transfer) during the call.
This is useful when:
* You're integrating Ambivert AI 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. Other providers
return `NotImplementedError` until a per-provider implementation lands. If you
need Twilio, Plivo, Telnyx, Vonage, ARI, or another provider, please open a
request on [GitHub Discussions](https://github.com/ambivert-hq/ambivert/discussions)
with your use case.
## Endpoint
```
wss://app.ambivertai.tech/api/v1/agent-stream/{agent_uuid}
```
`{agent_uuid}` is the agent's stable UUID (see [Get the Agent UUID](#get-the-agent-uuid) below). On self-hosted deployments, replace `app.ambivertai.tech` with your backend host.
## Prerequisites
* A Ambivert AI agent (workflow) — published or in draft is fine
* A Cloudonix telephony configuration in your Ambivert AI organization whose `domain_id` matches the `Domain` you pass on the URL. Ambivert AI 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](/configurations/agent-uuid).
## Connect to the WebSocket
### URL parameters
| Param | Required | Description |
| -------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | Yes | Provider name. Currently only `cloudonix` is supported. |
| `Domain` | Yes (cloudonix) | Cloudonix domain ID. Ambivert AI uses this to look up the matching stored telephony configuration and retrieve the bearer token used for provider API calls. |
| `callId` / `CallSid` | No | Call identifier from your side; persisted on the workflow run's `gathered_context` as `call_id`. The Cloudonix call SID used for streaming is taken from the `start` event payload, not this param. |
| `from` | No | Caller phone number, persisted on the workflow run as `caller_number`. |
| `to` | No | Called phone number, persisted on the workflow run as `called_number`. |
### Cloudonix example
```
wss://app.ambivertai.tech/api/v1/agent-stream/{agent_uuid}
?provider=cloudonix
&Domain={CLOUDONIX_DOMAIN_ID}
&callId={CALL_ID}
&from=+15555550100
&to=+15555550199
```
Use this URL inside the CXML `` your Cloudonix Voice Application returns when the call needs to be bridged to the Ambivert AI agent:
```xml theme={null}
```
The first two messages on the socket should be Cloudonix's standard `connected` and `start` events (Twilio-compatible framing). Ambivert AI extracts `streamSid` and `callSid` from the `start` event payload, validates the session against Cloudonix using the bearer token from the stored telephony configuration matched by `Domain`, and then begins streaming audio.
## Workflow run lifecycle
When the WebSocket is accepted, Ambivert AI:
1. Looks up the workflow by `agent_uuid`
2. Runs a quota check against the workflow's owning user
3. Creates a new `WorkflowRun` (`call_type=inbound`, `mode=cloudonix`, name `WR-AGS-XXXXXXXX`) with the `from`/`to` numbers stamped on `initial_context`, the `callId`/`CallSid` stored as `call_id` on `gathered_context`, and `Domain` recorded under the run's `inbound_webhook` log
4. Transitions the run to `running` and starts the agent pipeline
The run is visible under the agent's **Runs** tab as soon as it's minted, just like an inbound or outbound call.
## Close codes
| Code | Reason |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `1008` | Routing failure — unknown provider, workflow not found, or quota exceeded |
| `1011` | Server-side failure or unsupported provider for Agent Stream |
| `4400` | Provider-level handshake error — for cloudonix, missing `Domain`, no matching telephony configuration, missing bearer token on the configuration, malformed `connected`/`start` events, or session validation failed against Cloudonix |
## 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 `Domain` for Cloudonix) and are used server-side by Ambivert AI to validate the session and issue provider API calls.