Storage

Upload, download, and manage media files and other stored assets used across VoIPBIN services.

Overview

Note

AI Context

Complexity: Low
Cost: Chargeable (per GB stored; default quota is 10 GB per customer)
Async: No. File uploads and downloads are synchronous. POST /files returns immediately with the file metadata. GET /files/{id} returns file details including a time-limited uri_download.

VoIPBIN’s Storage API provides file management capabilities for storing and retrieving files associated with your communications. From call recordings to media attachments, the Storage API enables secure file operations within your allocated quota.

With the Storage API you can:

Upload files to cloud storage
Retrieve and download stored files
Delete files to manage quota
Monitor storage usage
Access file metadata and URLs

How Storage Works

VoIPBIN storage provides cloud-based file management with quota limits.

Storage Architecture

+-----------------------------------------------------------------------+
|                         Storage System                                |
+-----------------------------------------------------------------------+

+-------------------+
|  Storage Account  |
|   (quota: 10GB)   |
+--------+----------+
         |
         | contains
         v
+--------+----------+--------+----------+--------+----------+
|                   |                   |                   |
v                   v                   v                   v
+----------+   +----------+   +----------+   +----------+
| Recording|   |   Media  |   |  Export  |   |  Other   |
|  files   |   |   files  |   |  files   |   |  files   |
+----------+   +----------+   +----------+   +----------+
     |              |              |              |
     v              v              v              v
+---------+    +---------+    +---------+    +---------+
| .wav    |    | .jpg    |    | .csv    |    | .pdf    |
| .mp3    |    | .png    |    | .json   |    | .txt    |
+---------+    +---------+    +---------+    +---------+

Key Components

Storage Account: Your allocated storage space with quota
Files: Individual stored items with metadata
Quota: Maximum storage limit (currently 10GB)
Download URL: Secure link to access file content

File Operations

Core file management operations.

Note

AI Implementation Hint

The uri_download field in file responses contains a time-limited signed URL. Always check tm_download_expire before using the URL. If the URL has expired, fetch fresh file details via GET /files/{id} to get a new download URL. Do not cache or persist download URLs for long-term use.

Upload a File

$ curl -X POST 'https://api.voipbin.net/v1.0/files?token=<token>' \
    --header 'Content-Type: multipart/form-data' \
    --form 'file=@/path/to/file.pdf' \
    --form 'name=document.pdf'

Response:

{
    "id": "file-uuid-123",
    "name": "document.pdf",
    "size": 102400,
    "mime_type": "application/pdf",
    "download_url": "https://storage.voipbin.net/...",
    "tm_create": "2024-01-15T10:30:00Z"
}

List All Files

$ curl -X GET 'https://api.voipbin.net/v1.0/files?token=<token>'

Get File Details

$ curl -X GET 'https://api.voipbin.net/v1.0/files/<file-id>?token=<token>'

Delete a File

$ curl -X DELETE 'https://api.voipbin.net/v1.0/files/<file-id>?token=<token>'

Storage Account Management

Monitor and manage your storage usage.

Get Storage Usage

$ curl -X GET 'https://api.voipbin.net/v1.0/storage_accounts?token=<token>'

Response:

{
    "id": "storage-uuid-123",
    "customer_id": "customer-uuid-456",
    "total_size": 524288000,
    "file_count": 150,
    "quota": 10737418240,
    "tm_create": "2024-01-01T00:00:00Z"
}

Usage Breakdown

Storage Account:
+-----------------------------------------------------------------------+
|                                                                       |
|  Quota:      10 GB (10,737,418,240 bytes)                            |
|  Used:       500 MB (524,288,000 bytes)                              |
|  Available:  9.5 GB                                                  |
|  File Count: 150 files                                               |
|                                                                       |
|  Usage:      [#####------------------------------] 4.9%              |
|                                                                       |
+-----------------------------------------------------------------------+

File Types and Sources

Storage holds various file types from different sources.

Common File Types

Category	Extensions	Source
Call Recordings	.wav, .mp3	Automatic recording feature
Voicemail	.wav, .mp3	Voicemail recordings
Media Attachments	.jpg, .png, .gif	MMS and email attachments
Transcripts	.txt, .json	Call transcription exports
Reports	.csv, .pdf	Generated reports and exports

File Sources

+-------------------+
|  Call Recording   |---------------+
+-------------------+               |
                                    |
+-------------------+               v
|  Transcription    |-------> +----------+
+-------------------+         | Storage  |
                              | Account  |
+-------------------+         +----------+
|  MMS Attachment   |-------->      |
+-------------------+               |
                                    v
+-------------------+         +----------+
|  Manual Upload    |-------->| Files    |
+-------------------+         +----------+

Quota Management

Manage storage within your allocated quota.

Quota Check Flow

Upload Request
      |
      v
+-------------------+
| Check quota       |
| Used + New file   |
+--------+----------+
         |
         v
+-------------------+     Within limit
| Under quota?      |----------------------> Upload succeeds
+--------+----------+
         |
         | Exceeds quota
         v
+-------------------+
| Upload rejected   |
| Error: quota      |
| exceeded          |
+-------------------+

Managing Quota

Delete unnecessary files to free space
Export and archive old recordings
Monitor usage regularly
Request quota increase if needed

Common Scenarios

Scenario 1: Managing Call Recordings

Store and access call recordings.

1. Call with recording enabled
   +--------------------------------------------+
   | Call completed                             |
   | Recording saved to storage                 |
   | File: call-2024-01-15-abc123.wav          |
   +--------------------------------------------+

2. Access recording
   GET /files?type=recording
   -> List of recording files

3. Download recording
   GET /files/{id}
   -> download_url in response

4. Clean up old recordings
   DELETE /files/{id}
   -> Free storage space

Scenario 2: Storage Cleanup

Free up space when approaching quota.

1. Check current usage
   GET /storage_accounts
   +--------------------------------------------+
   | Used: 9.2 GB / 10 GB (92%)                |
   | Status: Near quota limit                  |
   +--------------------------------------------+

2. Identify large/old files
   GET /files?sort=size&order=desc
   -> Find largest files

   GET /files?sort=tm_create&order=asc
   -> Find oldest files

3. Delete unnecessary files
   DELETE /files/{id}
   (repeat for multiple files)

4. Verify freed space
   GET /storage_accounts
   +--------------------------------------------+
   | Used: 5.8 GB / 10 GB (58%)                |
   | Status: OK                                |
   +--------------------------------------------+

Scenario 3: Media File Management

Handle media attachments from messages.

Inbound MMS with image
     |
     v
+--------------------------------------------+
| Image saved to storage                     |
| File: mms-attachment-xyz.jpg               |
| Size: 2.5 MB                               |
+--------------------------------------------+
     |
     v
Access via API or webhook
+--------------------------------------------+
| download_url in message webhook            |
| GET file for processing                    |
+--------------------------------------------+

Best Practices

1. Quota Management

Monitor usage regularly
Set up alerts for high usage
Clean up old files periodically
Archive important files externally

2. File Organization

Use descriptive file names
Track file purpose via metadata
Group related files logically

3. Security

Download URLs are time-limited
Don’t share URLs publicly
Delete sensitive files when no longer needed

4. Performance

Delete files you no longer need
Don’t upload unnecessarily large files
Use appropriate file formats

Troubleshooting

Upload Issues

Symptom	Solution
Upload fails	Check file size; verify quota not exceeded; ensure file format is supported
Quota exceeded error	Delete old files; check storage usage; request quota increase

Download Issues

Symptom	Solution
Download URL expired	Get fresh file details; URLs are time-limited
File not found	Verify file ID; file may have been deleted

Management Issues

Symptom	Solution
File count mismatch	Allow time for sync; some operations are eventually consistent
Cannot delete file	Check file ID; verify permissions; file may be in use

Account

{
    "id": "<string>",
    "customer_id": "<string>",
    "total_file_count": <number>,
    "total_file_size": <number>,
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The storage account’s unique identifier. Returned when listing storage accounts via GET /storage_accounts.
customer_id (UUID): The customer who owns this storage account. Obtained from GET /customers.
total_file_count (Integer): Total number of files stored in this account.
total_file_size (Integer): Total size of all files in bytes. Divide by 1,073,741,824 to get size in GB.
tm_create (string, ISO 8601): Timestamp when the storage account was created.
tm_update (string, ISO 8601): Timestamp of the last update (e.g., file upload or deletion changed totals).
tm_delete (string, ISO 8601): Timestamp when the storage account was deleted. Set to 9999-01-01 00:00:00.000000 if 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 storage account has not been deleted. The total_file_size is in bytes; compare against the quota (default 10 GB = 10,737,418,240 bytes) to check remaining capacity.

Example

{
    "id": "1f8ccab9-1b64-11ef-8530-42010a7e5015",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "total_file_count": 2,
    "total_file_size": 221762,
    "tm_create": "2024-05-26 13:30:31.176034",
    "tm_update": "2024-05-27 07:55:17.016150",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

File

{
    "id": "<string>",
    "customer_id": "<string>",
    "owner_id": "<string>",
    "reference_type": "<string>",
    "reference_id": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "filename": "<string>",
    "filesize": <number>,
    "uri_download": "<string>",
    "tm_download_expire": "<string>",
    "tm_create": "2024-05-27 07:55:16.515315",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

id (UUID): The file’s unique identifier. Returned when uploading a file via POST /files or listing via GET /files.
customer_id (UUID): The customer who owns this file. Obtained from GET /customers.
owner_id (UUID): The agent who uploaded or owns this file. Obtained from GET /agents. Empty string if no specific owner.
reference_type (enum string): The type of resource this file is associated with. See Reference Type.
reference_id (UUID): The ID of the associated resource. Depending on reference_type, obtained from GET /recordings or other endpoints. Set to 00000000-0000-0000-0000-000000000000 if no reference.
name (String): A human-readable name for the file. May be empty if not explicitly set.
detail (String): A longer description of the file’s purpose or content. May be empty.
filename (String): The original filename of the uploaded file (e.g., screenshot.png, call_recording.wav).
filesize (Integer): The file size in bytes.
uri_download (String): A time-limited signed URL for downloading the file. Check tm_download_expire before using. Fetch fresh details via GET /files/{id} if expired.
tm_download_expire (string, ISO 8601): Expiration time of the uri_download. After this time, the URL is no longer valid.
tm_create (string, ISO 8601): Timestamp when the file was created.
tm_update (string, ISO 8601): Timestamp of the last update to any file property. Set to 9999-01-01 00:00:00.000000 if never updated after creation.
tm_delete (string, ISO 8601): Timestamp when the file was deleted. Set to 9999-01-01 00:00:00.000000 if 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 file has not been deleted. The uri_download is a time-limited signed URL; always check tm_download_expire before using it. If expired, call GET /files/{id} to obtain a fresh URL.

Example

{
    "id": "0c0c305c-7a55-4395-85a8-ae4860f01393",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_id": "62005165-7592-4ff7-9076-55bf491023f2",
    "reference_type": "",
    "reference_id": "00000000-0000-0000-0000-000000000000",
    "name": "",
    "detail": "",
    "filename": "Screenshot from 2024-05-26 21-58-51.png",
    "filesize": 110881,
    "uri_download": "https://example.com/storage_url",
    "tm_download_expire": "2034-05-25 07:55:16.115684",
    "tm_create": "2024-05-27 07:55:16.515315",
    "tm_update": "9999-01-01 00:00:00.000000",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Reference Type

All possible values for the reference_type field:

Reference Type	Description
none	The file has no associated resource. Typically for manually uploaded files. The `reference_id` will be `00000000-0000-0000-0000-000000000000`.
recording	The file is associated with a recording. The `reference_id` is a recording ID from `GET /recordings`.

Storage

Overview

How Storage Works

File Operations

Storage Account Management

File Types and Sources

Quota Management

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Account

Account

Example

File

File

Example

Reference Type