VoIPBin Documentation
Recording
Manage call recordings including starting, stopping, and retrieving recorded audio files from voice calls.
API Reference: Recording endpoints
Overview
Note
AI Context
Complexity: Medium
Cost: Chargeable (recording duration contributes to call costs; storage charged per GB)
Async: Yes. Recordings transition through states:
starting->recording->stopping->available. PollGET /recordings/{id}to check foravailablestatus before downloading.
VoIPBIN’s Recording API enables you to capture, store, and manage audio from calls and conferences. Whether you need recordings for compliance, quality assurance, training, or analytics, the Recording API provides a complete solution for managing call audio throughout its lifecycle.
With the Recording API you can:
Record calls and conferences in real-time
Start and stop recordings programmatically or via flow actions
Download recordings as audio files
Export recordings in bulk for archival
Manage recording lifecycle and storage
How Recording Works
When you start a recording, VoIPBIN captures the audio stream and writes it to cloud storage. The recording continues until you stop it, the call ends, or the maximum duration is reached.
Recording Architecture
+--------+ +----------------+ +-----------+
| Call |--audio-->| Recording |--file-->| Storage |
+--------+ | Engine | | (GCS) |
+----------------+ +-----------+
+------------+ |
| Conference |--audio----+
+------------+
Key Components
Audio Source: The call or conference being recorded
Recording Engine: Captures audio in real-time, handles encoding
Storage: Google Cloud Storage for reliable, scalable file storage
Recording Types
Type |
Description |
|---|---|
Call Recording |
Records a single call’s audio (both directions mixed) |
Conference Recording |
Records all participant audio mixed together |
File Format
Format: WAV (PCM)
Sample Rate: 8 kHz
Channels: Mono (all audio mixed)
Bit Depth: 16-bit
Recording Lifecycle
Every recording moves through a predictable set of states from creation to availability.
State Diagram
POST /recording_start or flow action
|
v
+------------+ +------------+
| starting |------recording-------->| recording |
+------------+ +-----+------+
|
POST /recording_stop, hangup, or max duration
|
v
+------------+
| stopping |
+-----+------+
|
v (file processing)
+------------+
| available |
+------------+
State Descriptions
State |
What’s happening |
|---|---|
starting |
Recording initialization. Audio capture is being set up. |
recording |
Actively capturing audio. File is being written to storage. |
stopping |
Recording is ending. Final audio is being flushed to storage. |
available |
Recording is complete. File is ready for download or streaming. |
Key Behaviors
States only move forward, never backward
A recording in “available” state cannot be modified
If the call/conference ends, active recordings automatically stop
Maximum recording duration is 24 hours
Starting and Stopping Recordings
VoIPBIN provides multiple ways to control recordings based on your use case.
Note
AI Implementation Hint
A recording can only be started on a call or conference that is in progressing status (i.e., answered). Attempting to start recording on a call that is still dialing or ringing will fail. Always verify the call status via GET /calls/{id} before issuing a recording start command.
Method 1: Via Flow Action
Use recording_start and recording_stop actions in your call flow for automatic recording control.
Your Flow VoIPBIN Storage
| | |
| recording_start action | |
+-------------------------->| |
| | Initialize recording |
| +-------------------------->|
| | |
| |<=====audio stream=======>|
| | |
| recording_stop action | |
+-------------------------->| |
| | Finalize recording |
| +-------------------------->|
| | |
Example flow with recording:
{
"actions": [
{
"type": "answer"
},
{
"type": "recording_start",
"option": {
"format": "wav"
}
},
{
"type": "talk",
"option": {
"text": "This call is being recorded for quality purposes."
}
},
{
"type": "connect",
"option": {
"destinations": [{"type": "tel", "target": "+15551234567"}]
}
},
{
"type": "recording_stop"
}
]
}
Method 2: Via API (Interrupt Method)
Start or stop recording on an active call or conference programmatically.
Start recording on a call:
$ curl -X POST 'https://api.voipbin.net/v1.0/calls/<call-id>/recording_start?token=<token>' \
--header 'Content-Type: application/json' \
--data '{
"format": "wav"
}'
Stop recording on a call:
$ curl -X POST 'https://api.voipbin.net/v1.0/calls/<call-id>/recording_stop?token=<token>'
Start recording on a conference:
$ curl -X POST 'https://api.voipbin.net/v1.0/conferences/<conference-id>/recording_start?token=<token>' \
--header 'Content-Type: application/json' \
--data '{
"format": "wav"
}'
When to Use Each Method
Method |
Best for |
|---|---|
Flow Action |
Automated recording based on call flow logic |
API (Interrupt) |
Dynamic control - start/stop based on external events |
Recording Storage
Recordings are stored securely in Google Cloud Storage and accessible via the VoIPBIN API.
Storage Architecture
Download: Stream:
+------+ GET /recordings/{id}/file +------+ GET (Range header)
| Your |------------------------------->| Your |<- - - - - - - - - - ->
| App |<--------full file--------------| App | chunks
+------+ | +------+ |
v v
+-------------+ +-------------+
| Recording | | Recording |
| File | | File |
+-------------+ +-------------+
Accessing Recordings
List all recordings:
$ curl -X GET 'https://api.voipbin.net/v1.0/recordings?token=<token>'
Get recording metadata:
$ curl -X GET 'https://api.voipbin.net/v1.0/recordings/<recording-id>?token=<token>'
Download recording file:
$ curl -X GET 'https://api.voipbin.net/v1.0/recordings/<recording-id>/file?token=<token>' \
--output recording.wav
Storage Details
Aspect |
Details |
|---|---|
Storage Location |
Google Cloud Storage (GCS) |
Retention Period |
Configurable per customer (default: 30 days) |
Maximum Duration |
24 hours per recording |
File Size |
~1 MB per minute (8 kHz mono WAV) |
Bulk Export
For exporting large numbers of recordings, use the asynchronous bulk export API:
$ curl -X POST 'https://api.voipbin.net/v1.0/recordings/export?token=<token>' \
--header 'Content-Type: application/json' \
--data '{
"recording_ids": [
"recording-id-1",
"recording-id-2",
"recording-id-3"
]
}'
The export runs asynchronously and you’ll receive a webhook when complete.
Recording and Calls/Conferences
Understanding how recordings relate to calls and conferences helps you track and manage them effectively.
Call Recording Relationship
+-------------------------------------------------------------------+
| Call |
| |
| recording_id: "abc-123" <- Currently active recording |
| |
| recording_ids: [ <- All recordings from this call |
| "abc-123", |
| "def-456", |
| "ghi-789" |
| ] |
| |
+-------------------------------------------------------------------+
recording_id: The currently active recording (empty if not recording)recording_ids: History of all recordings made during this call
Multiple Recordings Per Call
You can start and stop recording multiple times during a single call:
Call Timeline:
|-----|=========|-----|=========|-----|=========|----->
^ ^ ^ ^ ^ ^
| | | | | |
start stop start stop start stop
rec 1 rec 1 rec 2 rec 2 rec 3 rec 3
Result: 3 separate recording files
Common Scenarios
Scenario 1: Record Entire Call
Start recording immediately when the call is answered.
{
"actions": [
{"type": "answer"},
{"type": "recording_start"},
{"type": "connect", "option": {"destinations": [...]}},
{"type": "recording_stop"}
]
}
Scenario 2: Record Only After Consent
Play a consent message, then start recording.
Call answered
|
v
+------------------+
| "Press 1 to |
| consent to |
| recording" |
+--------+---------+
|
+----+----+
| |
Pressed 1 Other
| |
v v
Start Continue
Recording without
| recording
v
Continue
call
Scenario 3: Conference Recording
Record all participants in a conference.
Conference
+-------------------------------------------------------+
| +------+ +------+ +------+ |
| |User A| |User B| |User C| |
| +--+---+ +--+---+ +--+---+ |
| | | | |
| +-----+-----+-----+-----+ |
| | |
| v |
| +----------+ |
| |Recording | <- All audio mixed together |
| | File | |
| +----------+ |
+-------------------------------------------------------+
Scenario 4: Pause and Resume Recording
Stop and start recording to skip sensitive information.
Recording active
|
v
"Please provide your credit card number"
|
v
STOP recording
|
v
Customer provides card number (not recorded)
|
v
START recording (new recording file)
|
v
Continue call
Best Practices
1. Legal Compliance
Consent: Many jurisdictions require consent before recording. Always announce recordings.
Retention: Define clear retention policies. Delete recordings when no longer needed.
Access Control: Limit who can access recordings. Use VoIPBIN’s permission system.
2. Announcement Examples
{
"type": "talk",
"option": {
"text": "This call may be recorded for quality and training purposes.",
"language": "en-US"
}
}
3. Storage Management
Set appropriate retention periods for your use case
Use bulk export for long-term archival
Monitor storage usage to manage costs
Delete recordings that are no longer needed
4. Recording Quality
Ensure good network connectivity for clear audio
Monitor for recording failures via webhooks
Test recording playback regularly
Troubleshooting
Recording Not Starting
Symptom |
Solution |
|---|---|
No recording_id returned |
Verify call/conference is in “progressing” status before starting recording |
Permission denied |
Check API token has recording permissions |
Recording starts but immediately stops |
Check if another recording is already active (only one active recording per call) |
Empty or Corrupted Files
Symptom |
Solution |
|---|---|
File size is 0 bytes |
Recording may have been stopped immediately after starting. Ensure audio is flowing. |
File won’t play |
Verify file format. VoIPBIN uses WAV format. Some players may not support 8kHz mono. |
Audio is silent |
Check that audio was flowing during recording. Muted calls produce silent recordings. |
Download Failures
Symptom |
Solution |
|---|---|
404 Not Found |
Recording may still be processing. Wait for “available” status before downloading. |
Timeout on large files |
Use streaming download with Range headers for large recordings. |
Recording expired |
Recording exceeded retention period. Check your retention settings. |
Recording
Recording
{
"id": "<string>",
"type": "<string>",
"reference_id": "<string>",
"status": "<string>",
"format": "<string>",
"tm_start": "<string>",
"tm_end": "<string>",
"tm_create": "<string>",
"tm_update": "<string>",
"tm_delete": "<string>"
}
id(UUID): The recording’s unique identifier. Returned when creating a recording viaPOST /calls/{id}/recording_startor listing viaGET /recordings.type(enum string): The recording’s type. See Type.reference_id(UUID): The ID of the call or conference being recorded. Obtained fromGET /callsorGET /conferences.status(enum string): The recording’s current status. See Status.format(enum string): The recording file format. See Format.tm_start(string, ISO 8601): Timestamp when the recording started capturing audio.tm_end(string, ISO 8601): Timestamp when the recording stopped capturing audio.tm_create(string, ISO 8601): Timestamp when the recording resource was created.tm_update(string, ISO 8601): Timestamp of the last update to any recording property.tm_delete(string, ISO 8601): Timestamp when the recording was deleted. Set to9999-01-01 00:00:00.000000if not deleted.
Note
AI Implementation Hint
Timestamps set to 9999-01-01 00:00:00.000000 indicate the event has not yet occurred. For example, tm_delete with this value means the recording has not been deleted. An empty tm_delete ("") in older recordings also indicates not deleted.
Type
All possible values for the type field:
Type |
Description |
|---|---|
call |
Recording of a single call. Audio from both parties is mixed into one channel. The |
conference |
Recording of a conference. Audio from all participants is mixed together. The |
Status
All possible values for the status field:
Status |
Description |
|---|---|
initiating |
Preparing the recording. Audio capture is being set up. The recording file is not yet available. |
recording |
Actively capturing audio. The file is being written to storage in real-time. |
ended |
Recording is complete. The file is ready for download via |
Format
All possible values for the format field:
Format |
Description |
|---|---|
wav |
WAV format (PCM). 8 kHz sample rate, 16-bit, mono. Approximately 1 MB per minute of audio. |
Tutorial
Before working with recordings, you need:
An authentication token. Obtain one via
POST /auth/loginor use an access key fromGET /accesskeys.A call or conference with recording enabled. Start a recording via the
recording_startflow action or viaPOST /calls/{id}/recording_start.A recording ID (UUID). Obtain from the call’s
recording_idsfield viaGET /calls/{id}or by listing recordings viaGET /recordings.
Note
AI Implementation Hint
Recording files are only available for download after the recording reaches ended status. If you attempt to download immediately after stopping a recording, the file may not be ready. Poll GET /recordings/{id} and check for status: "ended" before calling GET /recordingfiles/{id}.
Get list of recordings
Example
$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/recordings?token=<YOUR_AUTH_TOKEN>&page_size=10&page_token=2021-05-03+21%3A35%3A02.809'
{
"result": [
{
"id": "348d988b-2ac9-4702-84f0-ae81301ad349",
"user_id": 1,
"type": "call",
"reference_id": "531bc6f4-c695-4c6d-a478-f28b88dfc2ca",
"status": "ended",
"format": "wav",
"filename": "call_531bc6f4-c695-4c6d-a478-f28b88dfc2ca_2021-01-29T05:31:45Z.wav",
"tm_start": "2021-01-29 05:31:47.870000",
"tm_end": "2021-01-29 05:31:58.932000",
"tm_create": "2021-01-29 05:31:45.051136",
"tm_update": "2021-01-29 05:31:58.943456",
"tm_delete": ""
},
{
"id": "142e8ef8-392c-4514-abf0-8656da5d2fdf",
"user_id": 1,
"type": "call",
"reference_id": "f457951b-9918-44af-a834-2216b1cc31bc",
"status": "ended",
"format": "wav",
"filename": "call_f457951b-9918-44af-a834-2216b1cc31bc_2021-01-29T03:18:07Z.wav",
"tm_start": "2021-01-29 03:18:10.790000",
"tm_end": "2021-01-29 03:18:22.131000",
"tm_create": "2021-01-29 03:18:07.950164",
"tm_update": "2021-01-29 03:18:22.144432",
"tm_delete": ""
},
{
"id": "f27d65bc-2f10-49e1-a49d-a7762965df13",
"user_id": 1,
"type": "call",
"reference_id": "5f7a0eff-9de9-4c41-a018-08bffd4a19aa",
"status": "ended",
"format": "wav",
"filename": "call_5f7a0eff-9de9-4c41-a018-08bffd4a19aa_2021-01-28T09:16:58Z.wav",
"tm_start": "2021-01-28 09:17:00.814000",
"tm_end": "2021-01-28 09:17:11.883000",
"tm_create": "2021-01-28 09:16:58.076735",
"tm_update": "2021-01-28 09:17:11.890500",
"tm_delete": ""
}
],
"next_page_token": "2021-01-28 09:16:58.076735"
}
Get detail of recording
Example
$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/recordings/f27d65bc-2f10-49e1-a49d-a7762965df13?token=<YOUR_AUTH_TOKEN>'
{
"id": "f27d65bc-2f10-49e1-a49d-a7762965df13",
"user_id": 1,
"type": "call",
"reference_id": "5f7a0eff-9de9-4c41-a018-08bffd4a19aa",
"status": "ended",
"format": "wav",
"filename": "call_5f7a0eff-9de9-4c41-a018-08bffd4a19aa_2021-01-28T09:16:58Z.wav",
"tm_start": "2021-01-28 09:17:00.814000",
"tm_end": "2021-01-28 09:17:11.883000",
"tm_create": "2021-01-28 09:16:58.076735",
"tm_update": "2021-01-28 09:17:11.890500",
"tm_delete": ""
}
Simple recordingfile download
Example
$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/recordingfiles/348d988b-2ac9-4702-84f0-ae81301ad349?token=<YOUR_AUTH_TOKEN>' -o tmp.wav
$ play tmp.wav 11s
tmp.wav:
File Size: 170k Bit Rate: 128k
Encoding: Signed PCM
Channels: 1 @ 16-bit
Samplerate: 8000Hz
Replaygain: off
Duration: 00:00:10.62
In:100% 00:00:10.62 [00:00:00.00] Out:85.0k [ | ] Hd:4.4 Clip:0
Done.