Media Handling

What is stored

• Media uploaded or referenced in outbound messages (images, video, audio, documents, stickers).
• Minimal metadata required for delivery and traceability (file name, mime type, size, checksum).

Access

Uploading Media

• Clients submit media via message payloads (base64 or HTTPS URL).
• After upload, the API references stored media internally for delivery.

Downloading Media

When you receive a webhook with media_path, you can download the media file using the API endpoint:

Authentication

Use your API key in the Authorization header:

Authorization: Bearer <your_token>

Example Request

From webhook payload:

{
  "payload": {
    "media_path": "media/b1580b43-f254-4a5e-bad3-6b16f49517d9/367ec376-2c93-45bc-ad97-bbbb42507021-AC4A3F9F8767CFB3DC015AA3A4805AC9.bin"
  }
}

Download the media:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-server.com/media?path=media/b1580b43-f254-4a5e-bad3-6b16f49517d9/367ec376-2c93-45bc-ad97-bbbb42507021-AC4A3F9F8767CFB3DC015AA3A4805AC9.bin" \
  --output image.jpg

Response

• Returns the media file with appropriate Content-Type header
• Supported types: image/jpeg, image/png, image/webp, video/mp4, audio/mpeg, audio/ogg, application/pdf
• Unknown types return as application/octet-stream

Security

• Only media files belonging to your app can be accessed
• Path traversal attacks are prevented
• API key authentication is required

Retention

• Media is retained only as long as needed for operational delivery and audit.
• Cleanup removes expired media automatically; deletions also occur when a device is destroyed.
• Older artifacts beyond internal retention windows are purged to conserve space and reduce risk.

Best Practices

• Use appropriate mime types and reasonable file sizes.
• Prefer widely supported audio formats (m4a/mp3) and standard image/video formats.
• Keep captions and file names concise for easier audit.