> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asisso.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Stream
> Stream audio to a Asisso 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 Asisso agent run. The agent UUID in the URL selects the agent; provider-specific identifiers in the query string (for Cloudonix: `Domain`) tell Asisso 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 Asisso to validate the session and to issue provider API calls (hangup, transfer) during the call.
This is useful when:
* You're integrating Asisso 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 contact
[support@asisso.com](mailto:support@asisso.com) with your use case.
## Endpoint
```
wss://app.asisso.com/api/v1/agent-stream/{agent_uuid}
```
`{agent_uuid}` is the agent's stable UUID (see [Get the Agent UUID](#get-the-agent-uuid) below).
## Prerequisites
* A Asisso agent (workflow) — published or in draft is fine
* A Cloudonix telephony configuration in your Asisso organization whose `domain_id` matches the `Domain` you pass on the URL. Asisso 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. You can copy it from two places in the dashboard:
**From the workflow editor**
1. Open your agent in the workflow editor
2. Click the **⋮** (more options) menu in the top-right of the header
3. Click **Copy Agent UUID** — the toast confirms the copy
**From the agent's Settings page**
1. Open the agent and go to **Settings**
2. Scroll to the **Agent UUID** section (also linked in the right-side nav)
3. Click the UUID code block, or use the **Copy UUID** button
## Connect to the WebSocket
### URL parameters
| Param | Required | Description |
| -------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | Yes | Provider name. Currently only `cloudonix` is supported. |
| `Domain` | Yes (cloudonix) | Cloudonix domain ID. Asisso 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.asisso.com/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 Asisso agent:
```xml theme={null}
```
The first two messages on the socket should be Cloudonix's standard `connected` and `start` events (Twilio-compatible framing). Asisso 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, Asisso:
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 Asisso to validate the session and issue provider API calls.