Call Duration & Background Audio

Two per-agent settings that shape the call’s outer envelope: a maximum call duration (graceful auto-end with farewell) and an ambient background audio track (mixed under the bot’s TTS for the duration of the call). Both are independent of each other and independent of the core agent prompt / voice / KB configuration.

Call duration cap

A hard cap on how long any single call can run. When the limit is reached, the bot speaks a farewell and ends the session through the standard end-of-call path so transcript, recording, billing and the session.completed webhook all fire normally.

Default

New agents default to max_call_duration_secs = 600 (10 minutes). You can override this between 60 and 3600 seconds (1 minute to 1 hour) per agent, or set it to null to disable the cap entirely. Existing agents created before this default landed may still hold null; opt them in by writing 600 via the agent update endpoint.

Behavior at the cap

The cap fires in two stages so the wind-down sounds natural:

Time	What the bot does
`cap − 30s`	Speaks a soft warning: “Just a heads up — we’re approaching the call time limit, so let’s wrap up shortly.” The conversation can continue.
`cap`	Speaks the agent’s `endCallMessage` (or a default farewell when none is set), then ends the call through the normal end-of-call path — transcript, recording, billing and the `session.completed` webhook all flow as if it were a normal hangup.

Setting the cap

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id} \
  -H "Authorization: Bearer rg_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "max_call_duration_secs": 900 }'

Set to null to disable:

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id} \
  -H "Authorization: Bearer rg_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "max_call_duration_secs": null }'

Background audio

Ambient audio mixed under the bot’s TTS for the duration of the call (office chatter, café noise, white noise, etc.). Looped continuously, volume tunable per agent. Vocobase handles playback and format normalization automatically.

Asset model

Two visibility tiers:

Platform-curated (is_platform: true) — visible to every account.
Your own uploads (owner_user_id: <yours>) — visible only to your account.

List both in one call:

curl -H "Authorization: Bearer rg_live_..." \
  https://api.vocobase.com/api/v2/agent/background-audio

Response:

{
  "success": true,
  "data": {
    "options": [
      {
        "id": "...",
        "slug": "office",
        "label": "Office",
        "is_platform": true,
        "duration_secs": 60.0,
        "preview_url": "https://storage.googleapis.com/..."
      }
    ]
  }
}

Uploading your own asset

Bytes go directly to a presigned upload URL. Vocobase then converts the file into the exact shape the bot needs and marks the asset ready. Accepted formats: wav, mp3, m4a, aac, ogg, opus, flac, webm, aiff. Constraints (enforced server-side):

Size: ≤ 5 MB.
Duration: ≤ 5 minutes (loops anyway). An over-length file is never quietly accepted — it either fails at finalize or, if its container declared no length for the check to read, ends up FAILED with the reason in error_message.

Channels and sample rate are not constraints. Stereo is downmixed and the audio is resampled for you — you do not need to know, or match, the rate the call runs at.

Compressed formats go further inside the 5 MB ceiling than WAV does. A one-minute bed is roughly 235 KB as a 32 kbps MP3 against roughly 937 KB as an 8 kHz WAV, so uploading MP3 rather than WAV buys you about four times the length.

# 1. Mint an upload URL
curl -X POST https://api.vocobase.com/api/v2/agent/background-audio/upload-url \
  -H "Authorization: Bearer rg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "my-cafe",
    "label": "My Café",
    "mime_type": "audio/mpeg",
    "size_bytes": 1234567
  }'
# → { "data": { "id": "<uuid>", "upload_url": "https://..." } }

# 2. PUT the bytes directly to the upload URL.
#    Content-Type must match the mime_type you sent in step 1 exactly,
#    or storage rejects the upload.
curl -X PUT "https://..." \
  -H "Content-Type: audio/mpeg" \
  --data-binary @my-cafe.mp3

# 3. Finalize — checks the file is decodable audio, then starts conversion
curl -X POST https://api.vocobase.com/api/v2/agent/background-audio/<id>/finalize \
  -H "Authorization: Bearer rg_live_..."
# → { "data": { "status": "UPLOADING", ... } }

# 4. Poll until conversion finishes
curl https://api.vocobase.com/api/v2/agent/background-audio/<id>/status \
  -H "Authorization: Bearer rg_live_..."
# → { "data": { "status": "READY", "duration_secs": 61.2, ... } }

finalize returns UPLOADING, not READY. Conversion runs after it responds, and an asset cannot be attached to an agent until it is READY — GET /agent/background-audio lists only READY assets, so a client that attaches immediately after finalize will not find it.Poll GET /agent/background-audio/{id}/status until status leaves UPLOADING. A FAILED status carries the reason in error_message.A 5 MB upload converts in seconds, but status polls count against the same 60 requests/minute limit as every other /api/v2 endpoint — poll once a second and you will spend your whole budget on the upload and start getting 429 on your call starts. Poll every 2-3 seconds, and back off on 429 using Retry-After. Give up after 60 seconds: an asset still UPLOADING by then is not going to finish, so surface it to the user as a failed upload and have them re-upload rather than polling on.An undecodable file still fails at finalize, immediately, with a specific error — so you get fast feedback on a genuinely bad upload.

Attaching to an agent

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id} \
  -H "Authorization: Bearer rg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "background_audio_id": "<asset-id>",
    "background_audio_volume": 0.4
  }'

background_audio_volume is 0.0-1.0. When null, the bot applies a default of 0.3.

Removing background audio from an agent

curl -X PUT https://api.vocobase.com/api/v2/agent/{agent_id} \
  -H "Authorization: Bearer rg_live_..." \
  -d '{ "background_audio_id": null }'

Deleting an asset you uploaded

curl -X DELETE \
  https://api.vocobase.com/api/v2/agent/background-audio/{id} \
  -H "Authorization: Bearer rg_live_..."

Soft-deletes the asset. Any agents currently referencing it are automatically detached (background_audio_id cleared).

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Call Duration & Background Audio

Call Duration & Background Audio

Call duration cap

Default

Behavior at the cap

Setting the cap

Background audio

Asset model

Uploading your own asset

Attaching to an agent

Removing background audio from an agent

Deleting an asset you uploaded

​Call Duration & Background Audio

​Call duration cap

​Default

​Behavior at the cap

​Setting the cap

​Background audio

​Asset model

​Uploading your own asset

​Attaching to an agent

​Removing background audio from an agent

​Deleting an asset you uploaded

Call Duration & Background Audio

Call duration cap

Default

Behavior at the cap

Setting the cap

Background audio

Asset model

Uploading your own asset

Attaching to an agent

Removing background audio from an agent

Deleting an asset you uploaded