Stream a call's audio to your WebSocket

POST

/calls/{id}/streams

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const mediaStream = await mv.calls.createStream("call_7Hk2Lm9Qp", {
  custom_parameters: {
    crm_id: "42",
  },
  format: "mulaw_8000",
  tracks: "both",
  url: "wss://media.example.com/streams",
});
console.log(mediaStream);

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

media_stream = client.calls.create_stream("call_7Hk2Lm9Qp", {
    "custom_parameters": {
        "crm_id": "42",
    },
    "format": "mulaw_8000",
    "tracks": "both",
    "url": "wss://media.example.com/streams",
})
print(media_stream)

curl -X POST https://api.morevoice.ai/v1/calls/call_7Hk2Lm9Qp/streams \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "custom_parameters": {
    "crm_id": "42"
  },
  "format": "mulaw_8000",
  "tracks": "both",
  "url": "wss://media.example.com/streams"
}'

Starts a media stream on a live call in fork mode: a one-way copy of the caller (inbound), what the caller hears (outbound), or both, sent to your wss:// URL as Twilio Media Streams messages (connected, start, media, stop). The call goes on exactly as before: if your server is slow, frames older than 2 s are dropped (frames_dropped); if it disconnects, the stream reconnects (3 tries) and otherwise gives up (failed) without touching the call. The upgrade request is signed with your signing secret over its path and query (webhook-id is the stream’s ID). The stream stops when the call ends or with DELETE. At most 2 streams per call.

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

<= 200 characters /^call_[0-9A-Za-z]+$/

A call ID (call_…).

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Idempotency-Key

string

>= 1 characters <= 255 characters

A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.

Example

5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body^required

application/json

Where and what to stream.

object

custom_parameters

Up to 20 string key/values the receiver gets in start.customParameters (as Twilio’s stream parameters).

object

key

additional properties

string

<= 500 characters

format

mulaw_8000 (the default): G.711 μ-law at 8 kHz, Twilio’s; l16_16000 / l16_8000: signed 16-bit PCM, little-endian.

string

default: mulaw_8000

Allowed values: mulaw_8000 l16_16000 l16_8000

mode

fork (the default): a one-way copy; your server’s messages are ignored.

string

default: fork

Allowed values: fork

tracks

inbound: the caller; outbound: what the caller hears (the assistant, an agent, prompts); both (the default).

string

default: both

Allowed values: inbound outbound both

url

required

Your WebSocket URL (wss://). The upgrade is signed with your signing secret (webhook-id, webhook-timestamp, webhook-signature over the path and query).

string

>= 1 characters <= 2048 characters

Example

{
  "custom_parameters": {
    "crm_id": "42"
  },
  "format": "mulaw_8000",
  "tracks": "both",
  "url": "wss://media.example.com/streams"
}

Responses

201

The stream, connecting.

application/json

A live copy of a call’s audio, sent to your WebSocket in the Twilio Media Streams format.

object

call_id

required

The call whose audio is streamed.

string

/^call_[0-9A-Za-z]+$/

created

required

An ISO-8601 timestamp in UTC.

string format: date-time

custom_parameters

required

object

key

additional properties

string

ended_reason

required

Why it ended: call_ended, stopped, receiver_closed or connect_failed; null while it runs.

string | null

format

required

mulaw_8000: G.711 μ-law at 8 kHz (Twilio’s); l16_16000 / l16_8000: signed 16-bit PCM, little-endian.

string

Allowed values: mulaw_8000 l16_16000 l16_8000

frames_dropped

required

Frames dropped because the receiver did not keep up (at most 2 s of audio waits per track).

integer

>= -9007199254740991 <= 9007199254740991

frames_sent

required

20 ms frames sent so far (all tracks).

integer

>= -9007199254740991 <= 9007199254740991

required

The stream’s ID (ms_…): streamSid in the protocol’s messages.

string

/^ms_[0-9A-Za-z]+$/

livemode

required

true in live mode, false in test mode.

boolean

mode

required

fork: a one-way copy of the call’s audio; the call goes on as before.

string

Allowed values: fork

object

required

string

Allowed value: media_stream

status

required

connecting (and reconnecting after the receiver dropped), streaming, stopped, or failed (the receiver could not be reached; the call went on).

string

Allowed values: connecting streaming reconnecting stopped failed

tracks

required

inbound: the caller; outbound: what the caller hears (the assistant, an agent, prompts); both.

string

Allowed values: inbound outbound both

url

required

The receiver’s WebSocket URL.

string

Example

{
  "call_id": "call_8tRPaZp5hLMbrGqdJ9AmNa",
  "created": "2026-11-03T09:14:22.000Z",
  "custom_parameters": {
    "crm_id": "42"
  },
  "ended_reason": null,
  "format": "mulaw_8000",
  "frames_dropped": 0,
  "frames_sent": 0,
  "id": "ms_4fG7hJ2kL9mN3pQ6rS8tUv",
  "livemode": true,
  "mode": "fork",
  "object": "media_stream",
  "status": "connecting",
  "tracks": "both",
  "url": "wss://media.example.com/streams"
}

400

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

The key may not do this (a missing scope, a plan limit, or a compliance block).

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

404

No object with this ID exists in this organisation and mode.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

409

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

Stream a call's audio to your WebSocket

Authorizations

Parameters

Path Parameters

Header Parameters

Example

Example

Request Bodyrequired

Example

Responses

201

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

404

Example

Headers

409

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required