dograh/docs/integrations/telephony/agent-stream.mdx

---
title: "Agent Stream"
description: "Stream audio to a Dograh 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 Dograh 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, Dograh 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 Dograh 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

<Warning>
  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/dograh-hq/dograh/discussions)
  with your use case.
</Warning>

## Endpoint

```
wss://app.dograh.com/api/v1/agent-stream/{provider}/{agent_uuid}
```

`{provider}` is the registered provider name, currently `cloudonix`. `{agent_uuid}` is the agent's stable UUID (see [Get the Agent UUID](#get-the-agent-uuid) below). On self-hosted deployments, replace `app.dograh.com` with your backend host.

## Prerequisites

- A Dograh agent (workflow) — published or in draft is fine
- A Cloudonix telephony configuration in your Dograh organization whose `domain_id` matches the `accountSid` Cloudonix sends in the stream `start` message. Dograh 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

### Path parameters

| Param | Required | Description |
| --- | --- | --- |
| `provider` | Yes | Provider name. Currently only `cloudonix` is supported. |
| `agent_uuid` | Yes | Stable UUID of the Dograh agent to run. |

### Cloudonix example

```
wss://app.dograh.com/api/v1/agent-stream/cloudonix/{agent_uuid}
```

Use this URL inside the CXML `<Stream>` your Cloudonix Voice Application returns when the call needs to be bridged to the Dograh agent:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Stream url="wss://app.dograh.com/api/v1/agent-stream/cloudonix/{agent_uuid}"/>
  </Connect>
  <Pause length="40"/>
</Response>
```

The first two messages on the socket should be Cloudonix's standard `connected` and `start` events (Twilio-compatible framing). Dograh 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, Dograh:

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`)
4. Transitions the run to `running`
5. Reads and validates the Cloudonix `start` message, then 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
6. 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 `start.accountSid`, 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 `start.accountSid` for Cloudonix) and are used server-side by Dograh to validate the session and issue provider API calls.