Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

Use this file to discover all available pages before exploring further.

When a contact sends you an image, video, audio file, document, or sticker, Titan captures the encrypted media reference from WhatsApp and surfaces it in the message.received webhook payload. From there, you can download the raw file or save it directly to your own S3-compatible storage bucket.
Titan does not store media on its servers. Files are either streamed directly to you on demand or saved to your own S3 bucket. Your data stays in your infrastructure.

​
Sending media

To send media in an outbound message, provide either a url (an HTTPS link to the file) or base64 (the file encoded as a base64 string) alongside the type field on the send messages endpoint.
Delivery methodMax size
url50 MB
base6470 MB
Supported formats:
  • Images: JPEG, PNG, WebP
  • Video: MP4
  • Audio: OGG, MP3
  • Documents: Any file type

​
Receiving media

Incoming media messages arrive via webhook with the standard message.received event. The payload includes:
  • mediaId — the Titan media record ID you use to download or persist the file
  • mimeType — the MIME type of the attachment (e.g. image/jpeg)
  • fileLength — file size in bytes
When your S3 auto-persist setting is enabled, the payload also contains mediaUrl — a direct URL to the file in your bucket.

​
Download media

Use the download endpoint to fetch the raw binary of a received media file. Titan downloads and decrypts the file from the WhatsApp CDN on the fly and streams it to you. 
POST /api/sessions/{session}/media/{mediaId}/download

curl -X POST https://api.titan.io/api/sessions/default/media/MEDIA_ID/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output file.jpg
The response is the raw binary of the media file. Use the Content-Type header from the response to determine the file format.

​
Persist media to S3

Instead of downloading the file yourself, you can instruct Titan to save it directly to your configured S3 bucket. This is useful when you want to archive media without handling binary data in your application. 
POST /api/sessions/{session}/media/{mediaId}/persist

curl -X POST https://api.titan.io/api/sessions/default/media/MEDIA_ID/persist \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
data
object

​
Auto-persist mode

You can configure Titan to automatically save all incoming media to your S3 bucket without calling the persist endpoint manually. When auto-persist is on, every incoming media message’s webhook payload includes the mediaUrl field pointing directly to the saved file. Enable auto-persist in the console under Settings → Media.
Auto-persist is the recommended approach for production workloads. You get a mediaUrl immediately in the webhook payload, so your application never needs to make a secondary API call to retrieve the file.

​
S3 configuration

Titan supports any S3-compatible object storage provider, including AWS S3, Cloudflare R2, and MinIO. Configure your bucket in the console under Settings → Storage by providing:
  • Endpoint — the S3 API endpoint URL (leave blank for AWS S3)
  • Bucket name — the target bucket
  • Region — e.g. us-east-1
  • Access key ID
  • Secret access key
Each tenant’s credentials are stored and used in isolation. Titan never shares storage configuration between accounts.
Ensure your bucket policy grants Titan write permissions. For AWS S3, the minimum required actions are s3:PutObject and s3:GetObject on the bucket and its objects.

​
Media metadata

The MediaInfo object, returned in webhook payloads and persist responses, contains the following fields:
​
id
string
Unique Titan media record identifier.
​
messageId
string
ID of the WhatsApp message that contained this media.
​
mimeType
string
MIME type of the file (e.g. image/jpeg, video/mp4, audio/ogg).
​
fileLength
integer
File size in bytes.
​
persisted
boolean
Whether the file has been saved to your S3 bucket.
​
s3Url
string
S3 URL of the file. Present only when persisted is true.
​
session
string
The session name that received this media.