Play audio on a call

POST

api

Account

{auth_id}

Call

{call_uuid}

Play

Play audio to a call

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "urls": "https://example.com/audio.mp3"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/"

payload = { "urls": "https://example.com/audio.mp3" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({urls: 'https://example.com/audio.mp3'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/

Play audio files during an active call. You can play a single file or multiple files in sequence, control which participants hear the audio, and configure looping and mixing behavior. Vobiz supports .mp3 and .wav audio files.

Audio files must be accessible via public HTTP or HTTPS URLs. Ensure your audio hosting service has proper CORS headers configured if needed.

Path parameters

Parameter	Type	Required	Description
`auth_id`	string	Yes	Your Vobiz authentication ID
`call_uuid`	string	Yes	Unique identifier of the active call

Request parameters

Field	Type	Required	Description
`urls`	string	Yes	Public `.mp3`/`.wav` audio URL to play. To play multiple files in sequence, pass a comma-separated list of URLs in this single string.
`length`	integer	No	Maximum playback duration in seconds.
`legs`	string	No	Which leg(s) to play on. Values: `aleg` (caller), `bleg` (callee), `both`. Default: `aleg`
`loop`	boolean	No	Whether to loop the audio. Default: `false`
`mix`	boolean	No	Whether to mix audio with the live call audio. Default: `true`

Pass comma-separated URLs to play files in sequence.
Set loop=true for hold music.
Set mix=false for important announcements so participants hear them clearly.
Use legs=both to play audio to all participants.

Error responses

Status	Meaning	How to handle
`400 Bad Request`	`urls` is missing/empty, or a URL is not a reachable `.mp3`/`.wav` file.	Host audio publicly over HTTP(S) and pass at least one valid URL.
`401 Unauthorized`	Missing/incorrect auth headers or a lowercase path.	Use both auth headers and the PascalCase path.
`404 Not Found`	The `call_uuid` is not an active call.	The call must be in-progress; confirm with Retrieve a Live Call.

Example request

{
  "urls": "https://example.com/audio/greeting.mp3",
  "length": 10,
  "legs": "both",
  "loop": false,
  "mix": true
}

{
  "urls": "https://example.com/intro.mp3,https://example.com/menu.mp3",
  "legs": "aleg"
}

curl -X POST https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": "https://example.com/audio/greeting.mp3",
    "legs": "both"
  }'

Response

202 Accepted

{
  "api_id": "uuid-here",
  "message": "play started"
}

Field	Description
`api_id`	Unique identifier for this API request
`message`	Confirmation that playback has started

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID

X-Auth-Token

string

header

required

Your Vobiz account Auth Token

Path Parameters

auth_id

string

required

Your account Auth ID

Example:

"MA_XXXXXX"

call_uuid

string

required

Body

application/json

urls

string

required

Example:

"https://example.com/audio.mp3"

legs

enum<string>

default:aleg

Available options:

aleg,

bleg,

both

loop

boolean

default:false

Response

200

Audio playback started

Play audio to a call

curl --request POST \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/ \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>' \
  --data '
{
  "urls": "https://example.com/audio.mp3"
}
'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/"

payload = { "urls": "https://example.com/audio.mp3" }
headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-ID': '<api-key>',
    'X-Auth-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({urls: 'https://example.com/audio.mp3'})
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Play/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

​Path parameters

​Request parameters

​Error responses

​Example request

​Response

Authorizations

Path Parameters

Body

Response

Path parameters

Request parameters

Error responses

Example request

Response