Skip to main content

Start Stream

Overview​

The start_stream action starts sending call media to your secure WebSocket endpoint. Use it for live transcription, monitoring, or real-time analysis. Place it in the actions array returned by your answer_url. MiniVoice executes actions in order, so put start_stream before the action that depends on its result and after any prompt or setup the caller should experience first.

Business Use Case​

Use start_stream when live audio is needed during the call, such as agent assist, live transcription, or monitoring. The stream target must be a secure WebSocket URL.

JSON Example​

{
  "actions": [
    {
      "start_stream": {
        "stream_url": "wss://media.example.com/minivoice",
        "track": "both"
      }
    }
  ]
}

Parameters​

FieldTypeRequiredDescription
typestringYesMust be start_stream when using typed action format.
stream_urlstringYesSecure WebSocket URL beginning with wss.
trackstringNoinbound, outbound, or both.

Execution Flow​

  1. MiniVoice validates stream_url and track.
  2. It opens media streaming to your WebSocket endpoint.
  3. Your server receives media for the selected track.
  4. Use stop_stream when you want to end streaming.

Webhook Behaviour​

No action-specific webhook is sent for start_stream. Your WebSocket server should log connection and media receipt.

Success Example​

A successful answer_url response includes the action in a valid actions array:

{
  "actions": [
    {
      "start_stream": {
        "stream_url": "wss://media.example.com/minivoice",
        "track": "both"
      }
    }
  ]
}

Your application should store the MiniVoice call ID from webhooks or API responses so you can correlate the action with the call.

Failure Behaviour​

Non-secure URLs are rejected. Streaming can fail if your WebSocket endpoint is unavailable or closes the connection.

Expected Result​

MiniVoice opens a media stream to the configured wss URL and sends the selected track while the call continues.

Testing​

Run a local WebSocket receiver through a secure tunnel, start a call, and confirm the receiver sees a connection for the selected track. During testing, log every webhook payload and compare the call ID, action timing, and final call status with the behavior you expected.

Copy/Paste Examples​

Real Request​

Return this from your answer_url:

{
  "actions": [
    {
      "start_stream": {
        "stream_url": "wss://media.example.com/minivoice",
        "track": "both"
      }
    }
  ]
}

Real Response​

A valid answer_url response is the JSON action payload itself. MiniVoice accepts the response when it contains an actions array:

{
  "actions": [
    {
      "start_stream": {
        "stream_url": "wss://media.example.com/minivoice",
        "track": "both"
      }
    }
  ]
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Use start_stream when live audio is needed during the call, such as agent assist, live transcription, or monitoring. The stream target must be a secure WebSocket URL.

Common Failure Case​

{
  "error": {
    "code": "answer_url_error",
    "message": "invalid action payload"
  }
}

Invalid fields or malformed JSON cause MiniVoice to reject the answer_url payload. Log the exact response your server returned while testing.