Media & File Attachments

Opengram supports file and media attachments in chat messages. Users can share images, documents, and other files directly in the conversation, and agents can access the uploaded content through the API.

Uploading Files

Users can attach files to messages through several methods:

• File picker -- click the attachment icon in the composer
• Camera -- take a photo on mobile devices using the camera input

Files are uploaded via POST /api/v1/chats/:chatId/media and attached to messages by referencing their file ID.

Upload Limits

Two configuration options control what can be uploaded:

These are set in your configuration file. If allowedMimeTypes is not specified, all file types are accepted.

SVG uploads are always blocked regardless of the allowedMimeTypes setting, due to security risks (embedded scripts).

Upload formats

The API supports two upload formats:

Multipart form data -- standard file upload with a file field:

curl -X POST /api/v1/chats/chat_123/media \
  -H "Authorization: Bearer og_..." \
  -F "file=@photo.jpg"

Optional form fields: kind (override auto-detection) and messageId (attach to a message on upload).

JSON with base64 data -- useful when your agent already has the file in memory:

curl -X POST /api/v1/chats/chat_123/media \
  -H "Authorization: Bearer og_..." \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "report.pdf",
    "contentType": "application/pdf",
    "base64Data": "JVBERi0xLjQK..."
  }'

Optional JSON fields: kind (override auto-detection) and messageId (attach to a message on upload).

Media kind auto-detection

If you do not specify a kind when uploading, Opengram detects it from the content type:

Thumbnails

Image attachments automatically get a thumbnail generated on upload. Thumbnails are served at a separate endpoint for efficient loading in the chat list and message bubbles:

• Full file: GET /api/v1/files/:mediaId
• Thumbnail: GET /api/v1/files/:mediaId/thumbnail

File Preview

Opengram includes a built-in file preview system. When a user taps on an attached file, it opens in a preview dialog rather than downloading immediately.

Supported preview types:

Text-based previews support files up to 20 MB. PDFs have no size limit for preview.

Media Gallery

Each chat has a media gallery drawer that shows all files shared in the conversation. Users can open it from the chat header to browse and access any attachment without scrolling through messages.

Range requests

File downloads support HTTP range requests (Range: bytes=0-1023), returning 206 Partial Content. This enables video/audio seeking and resumable downloads.

API Reference

• Upload media -- POST /api/v1/chats/:chatId/media
• Get media metadata -- GET /api/v1/media/:mediaId
• Download file -- GET /api/v1/files/:mediaId
• Download thumbnail -- GET /api/v1/files/:mediaId/thumbnail
• List chat media -- GET /api/v1/chats/:chatId/media
• Delete media -- DELETE /api/v1/media/:mediaId