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 Titan receives a WhatsApp message containing media (images, video, audio, documents, stickers), it records the media reference in a media object and delivers the media ID in the webhook event payload. You use the media ID to download the file, retrieve its metadata, or persist it to your own S3-compatible bucket. Media files on WhatsApp’s CDN expire after approximately 14 days. Persist important files to your own storage using the persist endpoint.
The mediaId appears in message.received webhook events for messages of type image, video, audio, document, and sticker. Store it from the webhook payload so you can fetch or persist the media later.

​
Media object

​
id
string
Unique media identifier.
​
messageId
string
ID of the WhatsApp message that contained this media.
​
session
string
Session where the media was received.
​
mimeType
string
MIME type of the media file (e.g. image/jpeg, video/mp4).
​
fileLength
integer
Size of the media file in bytes.
​
persisted
boolean
Whether the media has been saved to S3.
​
s3Url
string
S3 URL of the persisted file. Present only when persisted is true.

​
Get media metadata

curl https://api.example.com/api/sessions/default/media/abc123def456 \
  -H "Authorization: Bearer titan_..."
GET /api/sessions/{session}/media/{mediaId} Returns metadata for a media record without downloading the file.
​
session
string
required
Session name.
​
mediaId
string
required
Media ID from a webhook event payload.
{
  "data": {
    "id": "abc123def456",
    "messageId": "ABCDEF1234567890",
    "session": "default",
    "mimeType": "image/jpeg",
    "fileLength": 102400,
    "persisted": false,
    "s3Url": null
  }
}

​
Download media

curl -X POST https://api.example.com/api/sessions/default/media/abc123def456/download \
  -H "Authorization: Bearer titan_..." \
  --output photo.jpg
POST /api/sessions/{session}/media/{mediaId}/download Downloads the raw media file from WhatsApp’s CDN, decrypts it, and returns the binary content. The response Content-Type header reflects the media’s MIME type. Alternatively, the endpoint may return a 302 redirect to the media URL if your configuration uses direct streaming. In that case, follow the redirect to fetch the file.
​
session
string
required
Session name.
​
mediaId
string
required
Media ID from a webhook event payload.
Media files on WhatsApp’s CDN expire after approximately 14 days. Download or persist media promptly after receiving the webhook event.

​
Persist media to S3

curl -X POST https://api.example.com/api/sessions/default/media/abc123def456/persist \
  -H "Authorization: Bearer titan_..."
POST /api/sessions/{session}/media/{mediaId}/persist Downloads the media from WhatsApp, decrypts it, and uploads it to your configured S3-compatible bucket. You must configure your S3 credentials in your account settings before using this endpoint.
​
session
string
required
Session name.
​
mediaId
string
required
Media ID from a webhook event payload.
​
url
string
Public or presigned URL of the uploaded object in your S3 bucket.
​
key
string
S3 object key (path within the bucket).
​
bucket
string
Name of the S3 bucket where the file was stored.
​
size
integer
Size of the uploaded file in bytes.
​
mimeType
string
MIME type of the uploaded file.
{
  "data": {
    "url": "https://my-bucket.s3.amazonaws.com/media/abc123def456.jpg",
    "key": "media/abc123def456.jpg",
    "bucket": "my-media-bucket",
    "size": 102400,
    "mimeType": "image/jpeg"
  }
}

​
Auto-persist mode

Instead of manually persisting each media file, you can enable auto-persist in your account settings. When enabled, Titan automatically saves all incoming media to your S3 bucket as it arrives. The message.received webhook payload will include a mediaUrl field with the S3 URL instead of requiring a separate persist call.