Start conference listen

POSThttps://{API_ENDPOINT}/v1/Accounts/{AccountSid}/Conferences/{ConferenceName}/listenContent-Type: application/json

Streams the conference's mixed audio (L16 PCM) to the supplied WebSocket URL. Addressed by conference name — no participant call leg is required. The fork is media-server-owned: it is excluded from participant counts, never keeps a room alive, and is torn down automatically when the conference ends. Starting a fork for a conference that already has one is idempotent and returns the existing bot member (200 rather than 201).

Authentication

Authorization header (bearer token, required) — Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

Path parameters

AccountSidstringrequired
ConferenceNamestringrequired

Body (application/json)

This endpoint expects an object.

urlstringrequiredws(s):// URL the media server streams the room mix to
sampleRateintegeroptionalPCM sample rate of the fork (e.g. 8000, 16000)
wsAuthws_authoptionalHTTP basic-auth credentials presented on the WebSocket connection
metadataobjectoptionalArbitrary JSON delivered verbatim as the fork's first text frame, so the receiving WebSocket can identify and configure itself

Response

200

a listen fork is already active for this conference (idempotent)

botMemberIdintegeroptional
botIdstringoptional

201

listen fork started

botMemberIdintegeroptionalconference member id of the fork bot
botIdstringoptional

Errors

400 Bad Request Error

url is required

any

404 Not Found Error

no such conference

any

502 Bad Gateway Error

the media server hosting the conference is unknown or unreachable

any

Types

ws_auth

HTTP basic-auth credentials presented on the WebSocket connection

usernamestringoptional
passwordstringoptional

Examples

Example 1

Request

{
  "url": "wss://audio-streaming.example.com/conference123/mix"
}

Response

{
  "botMemberId": 42,
  "botId": "bot-7f3a9c2d"
}

cURL

curl -X POST "https://{API_ENDPOINT}/v1/Accounts/AccountSid/Conferences/ConferenceName/listen" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "wss://audio-streaming.example.com/conference123/mix"
}'

Python

import requests

url = "https://{API_ENDPOINT}/v1/Accounts/AccountSid/Conferences/ConferenceName/listen"

payload = { "url": "wss://audio-streaming.example.com/conference123/mix" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

JavaScript

const url = 'https://{API_ENDPOINT}/v1/Accounts/AccountSid/Conferences/ConferenceName/listen';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"url":"wss://audio-streaming.example.com/conference123/mix"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Request

{
  "url": "wss://audio-streaming.example.com/conference123/mix"
}

Response

{
  "botMemberId": 42,
  "botId": "bot-7f3a9c2d"
}

cURL

curl -X POST "https://{API_ENDPOINT}/v1/Accounts/AccountSid/Conferences/ConferenceName/listen" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "wss://audio-streaming.example.com/conference123/mix"
}'

Python

import requests

url = "https://{API_ENDPOINT}/v1/Accounts/AccountSid/Conferences/ConferenceName/listen"

payload = { "url": "wss://audio-streaming.example.com/conference123/mix" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

JavaScript

const url = 'https://{API_ENDPOINT}/v1/Accounts/AccountSid/Conferences/ConferenceName/listen';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"url":"wss://audio-streaming.example.com/conference123/mix"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}