Overview

Note

AI Context

• Complexity: Medium

• Cost: Chargeable. Billing runs for the duration between the recording’s tm_start and tm_end (a separate billing line item from the underlying call/conference). There is currently no separate per-GB storage charge.

• Async: Yes. Recordings transition through states: initiating -> recording -> stopping -> ended. Poll GET https://api.voipbin.net/v1.0/recordings/{id} to check for ended status 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
+-------------+                        +------------+
| initiating  |------recording-------->|  recording |
+-------------+                        +-----+------+
                                             |
                       POST /recording_stop, hangup, or max duration
                                             |
                                             v
                                      +------------+
                                      |  stopping  |
                                      +-----+------+
                                            |
                                            v (file processing)
                                      +------------+
                                      |   ended    |
                                      +------------+

State Descriptions

State	What’s happening
initiating	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.
ended	Recording is complete. File is ready for download or streaming.

Key Behaviors

• States only move forward, never backward

• A recording in ended state cannot be modified

• If the call/conference ends, active recordings automatically stop

• There is no fixed platform-wide maximum recording duration; pass the duration field to recording_start to cap a given recording, or leave it unset (0) for no automatic cap

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 https://api.voipbin.net/v1.0/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"
    }'

The request body also accepts these optional fields (all default to their zero value – 0/empty – when omitted, which disables the corresponding limit):

• end_of_silence (Integer): Stop the recording automatically after this many seconds of silence.

• end_of_key (String): A DTMF digit that, when pressed on the call, stops the recording.

• duration (Integer): Maximum recording duration in seconds. The recording stops automatically once reached.

• on_end_flow_id (UUID): A flow to execute automatically once the recording ends.

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:
+------+   GET /recordingfiles/{id}
| Your |------------------------------->
| App  |<--------full file--------------
+------+              |
                      v
               +-------------+
               |  Recording  |
               |    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/recordingfiles/<recording-id>?token=<token>' \
    --output recording.wav

Storage Details

Aspect	Details
Storage Location	Google Cloud Storage (GCS)
Retention Period	No automatic expiry/retention policy. Use DELETE /recordings/{id} to remove a recording explicitly when you no longer need it.
Maximum Duration	No fixed platform-wide cap. Optionally bounded per recording via the duration field on recording_start.
File Size	~1 MB per minute (8 kHz mono WAV)

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

• The platform does not auto-delete recordings, so build your own retention/cleanup process for your compliance needs, calling DELETE /recordings/{id} on a schedule that fits your policy

• 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 ended status before downloading.
Timeout on large files	Use streaming download with Range headers for large recordings.
Recording not found	The recording may have been explicitly deleted via DELETE /recordings/{id}. There is no automatic expiry, so a missing recording means it was deleted or the ID is wrong.

Related Documentation

• Call Overview - Recording calls

• Conference Overview - Recording conferences

• Transcribe Overview - Transcribing recordings