Call Actions
Perform actions on an active call — transfer, record, play audio, speak text, send DTMF.
Call Actions
Operate on calls that are already in progress. Every action endpoint is fire-and-forget: TryVox returns 204 No Content on success and the side effect happens asynchronously on the media server. There is no synchronous "operation completed" response — wire up webhooks (hangup_url, status_callback_url, recording callback_url) to observe results.
{call_uuid} in every URL is the call_uuid returned when the call was created (or surfaced in the inbound answer_url payload).
Transfer Call
Re-route an active call to a different VoxML script. Supports transferring the A leg, the B leg, or both.
Endpoint
POST https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls/{call_uuid}/transferRequest body
| Parameter | Type | Required | Description |
|---|---|---|---|
legs | string | no | aleg, bleg, or both. Default: aleg. |
aleg_url | string | conditional | New VoxML URL for the A leg. Required when legs is aleg or both. |
bleg_url | string | conditional | New VoxML URL for the B leg. Required when legs is bleg or both. |
Example request
curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls/650e8400-e29b-41d4-a716-446655440000/transfer \
-u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"legs": "aleg",
"aleg_url": "https://example.com/transfer-answer"
}'Response
204 No Content on accept. The leg fetches the new VoxML asynchronously. Failure to reach the URL fires the configured fallback_url.
Start Recording
Begin recording an in-progress call. The recording runs asynchronously; when it ends (because you called Stop, the call hangs up, or time_limit elapses) TryVox POSTs the recording details to your callback_url.
Endpoint
POST https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls/{call_uuid}/recordRequest body
| Parameter | Type | Required | Description |
|---|---|---|---|
time_limit | integer | no | Maximum recording duration in seconds. The recording auto-stops when it elapses. |
file_format | string | no | mp3 or wav. Default: mp3. |
transcription_type | string | no | auto to enable automatic speech-to-text transcription. Omit to skip. |
transcription_url | string | no | Webhook URL to receive transcript when transcription completes. |
callback_url | string | no | Webhook URL to receive the recording metadata (URL, duration, file size) when recording finishes. |
callback_method | string | no | HTTP method for callback_url. Default: POST. |
Example request
curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls/650e8400-e29b-41d4-a716-446655440000/record \
-u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"time_limit": 3600,
"file_format": "mp3",
"callback_url": "https://your-app.com/recording-callback"
}'Response
204 No Content. There's no synchronous recording URL — receive it via callback_url.
Recording webhook payload
When recording finishes, TryVox POSTs to your callback_url:
{
"event": "recording.completed",
"recording_id": "rec_950e8400e29b41d4a716446655440000",
"call_uuid": "650e8400-e29b-41d4-a716-446655440000",
"url": "https://recordings.tryvox.io/<account_id>/<recording_id>.mp3",
"duration": 125,
"file_format": "mp3",
"file_size_bytes": 1024000,
"started_at": "2026-04-09T10:30:15Z",
"ended_at": "2026-04-09T10:32:20Z"
}See Recordings for the full delivery model and retention policy.
Stop Recording
End an in-progress recording before time_limit is reached.
Endpoint
DELETE https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls/{call_uuid}/recordExample request
curl -X DELETE https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls/650e8400-e29b-41d4-a716-446655440000/record \
-u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKENResponse
204 No Content. The recording finalises asynchronously; the URL still arrives via the callback_url you registered when starting.
Play Audio
Stream one or more audio files into an active call. Multiple URLs are queued in order. Use loop for hold music, mix to overlay (e.g. background ambience while TTS plays).
Endpoint
POST https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls/{call_uuid}/playRequest body
| Parameter | Type | Required | Description |
|---|---|---|---|
urls | string[] | yes | Array of public URLs to mp3/wav files. Played in order. |
length | integer | no | Maximum playback duration in seconds. Truncates if the audio is longer. |
legs | string | no | aleg, bleg, or both. Default: aleg. |
loop | boolean | no | Loop the playlist indefinitely. Default: false. |
mix | boolean | no | Mix with existing audio instead of interrupting. Default: false. |
Example request
curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls/650e8400-e29b-41d4-a716-446655440000/play \
-u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://example.com/hold-music.mp3"],
"loop": true
}'Response
204 No Content.
Speak Text
Convert text to speech and play it on the call.
Endpoint
POST https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls/{call_uuid}/speakRequest body
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | yes | Text to synthesise. Max 3000 characters. |
voice | string | no | Voice ID. Default: provider default for language. |
language | string | no | BCP-47 language tag (e.g. en-US, en-IN, hi-IN). Default: en-US. |
legs | string | no | aleg, bleg, or both. Default: aleg. |
loop | boolean | no | Repeat the synthesised audio. Default: false. |
mix | boolean | no | Mix with existing audio. Default: false. |
Example request
curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls/650e8400-e29b-41d4-a716-446655440000/speak \
-u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"text": "Thank you for calling. Please hold while we connect you.",
"voice": "en-US-Neural-Jenny",
"language": "en-US"
}'Response
204 No Content.
Send DTMF
Send DTMF (touch-tone) digits onto a leg of the call. Useful for navigating an IVR after a transfer.
Endpoint
POST https://api.tryvox.io/v1/voice/accounts/{auth_id}/calls/{call_uuid}/dtmfRequest body
| Parameter | Type | Required | Description |
|---|---|---|---|
digits | string | yes | Sequence of DTMF digits: 0–9, *, #, A–D. |
leg | string | no | aleg or bleg. Default: aleg. |
Example request
curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls/650e8400-e29b-41d4-a716-446655440000/dtmf \
-u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{"digits": "1234*#"}'Response
204 No Content. Each digit plays for ~200ms with a 200ms gap.
Notes
- All actions require the call to be in
in-progressstate. Calling them on aqueued,ringing, orcompletedcall returns409 INVALID_STATE. - Actions execute asynchronously; the
204response means "accepted", not "applied". - Newly-started Play or Speak interrupts any in-flight Play or Speak unless
mix: trueis set. - Audio URLs must be publicly reachable. TryVox will not follow redirects past 3 hops.
- Recordings of both legs are mixed into a single file. There is no per-leg mode currently.
- Failed transfers fall back to the original call's
fallback_url; if no fallback is configured, the leg hangs up.