Agent Stream

Overview#

Agent Stream is a WebSocket endpoint that lets a telephony provider point its media stream at a single URL and drive a Menace 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, Menace Voice 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 Menace Voice 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#

wss://voice.menaceui.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 below). On self-hosted deployments, replace voice.menaceui.com with your backend host.

Prerequisites#

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

wss://voice.menaceui.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 Menace Agent:

<?xml version="1.0" encoding="UTF-8"?><Response>  <Connect>    <Stream url="wss://voice.menaceui.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). Menace Voice 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, Menace Voice:

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#

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 Menace Voice to validate the session and issue provider API calls.