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 https://api.voipbin.net/v1.0/storage_files returns immediately with the file metadata. GET https://api.voipbin.net/v1.0/storage_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, use GET https://api.voipbin.net/v1.0/storage_files/{id}/file which automatically refreshes the URL and redirects to the download. Do not cache or persist download URLs for long-term use.

Upload a File

$ curl -X POST 'https://api.voipbin.net/v1.0/storage_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/storage_files?token=<token>'

Get File Details

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

Download a File (Direct)

$ curl -L -X GET 'https://api.voipbin.net/v1.0/storage_files/<file-id>/file?token=<token>' \
    --output downloaded_file.pdf

Note

AI Implementation Hint

GET https://api.voipbin.net/v1.0/storage_files/{id}/file returns an HTTP 307 Temporary Redirect to a time-limited signed Google Cloud Storage URL. The Location header contains the actual download URL. Most HTTP clients (curl with -L, browsers, requests with allow_redirects=True) follow the redirect automatically. The {id} parameter is the file’s UUID, obtained from the id field of GET https://api.voipbin.net/v1.0/storage_files. This endpoint requires CustomerAdmin or CustomerManager permission. If the stored download URL has expired, the server automatically refreshes it before redirecting – so unlike uri_download from GET /storage_files/{id}, you never need to worry about expiration.

Response:

The server responds with HTTP 307 and a Location header:

HTTP/1.1 307 Temporary Redirect
Location: https://storage.googleapis.com/bucket-name/storage/file-uuid?X-Goog-Signature=...&X-Goog-Expires=...

The client follows the redirect and receives the file content directly from the storage backend.

Delete a File

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

Service Agent File Download

Service agents have their own file storage scoped to the authenticated agent. Files uploaded via POST /service_agents/files (e.g., talk attachments) can be downloaded using the same redirect pattern as storage files.

Download a Service Agent File

$ curl -L -X GET 'https://api.voipbin.net/v1.0/service_agents/files/<file-id>/file?token=<token>' \
    --output downloaded_file.pdf

Note

AI Implementation Hint

GET https://api.voipbin.net/v1.0/service_agents/files/{id}/file behaves identically to the storage file download: it returns an HTTP 307 Temporary Redirect to a time-limited signed URL. The {id} parameter is the file’s UUID, obtained from the id field of GET https://api.voipbin.net/v1.0/service_agents/files. Unlike GET /storage_files/{id}/file which requires CustomerAdmin or CustomerManager permission, this endpoint requires only that the file belongs to the same customer as the authenticated agent. If the download URL has expired, the server refreshes it automatically before redirecting.

Response:

The server responds with HTTP 307 and a Location header:

HTTP/1.1 307 Temporary Redirect
Location: https://storage.googleapis.com/bucket-name/storage/file-uuid?X-Goog-Signature=...&X-Goog-Expires=...

Storage Account Management

Monitor and manage your storage usage.

Get Storage Usage

$ curl -X GET 'https://api.voipbin.net/v1.0/storage_account?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 /storage_files?type=recording
   -> List of recording files

3. Download recording
   GET /storage_files/{id}/file
   -> HTTP 307 redirect to signed download URL
   (or GET /storage_files/{id} for metadata + download_url)

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

Scenario 2: Storage Cleanup

Free up space when approaching quota.

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

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

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

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

4. Verify freed space
   GET /storage_account
   +--------------------------------------------+
   | 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	Use `GET https://api.voipbin.net/v1.0/ storage_files/{id}/file` for automatic refresh
307 redirect not followed	Ensure your HTTP client follows redirects (curl `-L`, requests `allow_redirects=True`)
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_type": "<string>",
    "owner_id": "<string>",
    "reference_type": "<string>",
    "reference_id": "<string>",
    "type": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "filename": "<string>",
    "filesize": <number>,
    "uri_download": "<string>",
    "tm_download_expire": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The file’s unique identifier. Returned when uploading a file via POST /storage_files or listing via GET /storage_files.
customer_id (UUID): The customer who owns this file. Obtained from GET /customers.
owner_type (enum string): The type of owner for this file. Possible values: agent (owned by a specific agent), or empty string (no specific owner).
owner_id (UUID): The agent who uploaded or owns this file. When owner_type is agent, obtained from GET /agents. Set to 00000000-0000-0000-0000-000000000000 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.
type (enum string): The file type. See File Type.
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 /storage_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 /storage_files/{id} to obtain a fresh URL.

Example

{
    "id": "0c0c305c-7a55-4395-85a8-ae4860f01393",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "62005165-7592-4ff7-9076-55bf491023f2",
    "reference_type": "",
    "reference_id": "00000000-0000-0000-0000-000000000000",
    "type": "",
    "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`.

File Type

All possible values for the type field:

Type	Description
(empty)	No specific type assigned.
rag	A file used for RAG (Retrieval-Augmented Generation) knowledge base.
talk	A file associated with talk/conversation context.
recording	A recording file.

Storage

Overview

How Storage Works

File Operations

Service Agent File Download

Storage Account Management

File Types and Sources

Quota Management

Common Scenarios

Best Practices

Troubleshooting

Related Documentation

Account

Account

Example

File

File

Example

Reference Type

File Type