Media Upload API - Send Files and Images by API

Overview

The Media Upload API stores a file in your workspace's media storage and returns a media_url. You then pass that URL to the Send Messages API to send the file as an image, video, audio clip or document.

Uploading first is required for every channel except the WhatsApp Cloud API. WhatsApp fetches media from any public https URL itself, but Instagram, Messenger, Telegram, SMS, email and web chat sends only accept files stored in ChatMaxima.

Prerequisites

• An API key on a plan with API access (Pro or higher). See ChatMaxima API.
• A file smaller than 10 MB of an allowed type.

Upload a file

Send the file as multipart/form-data in a field named file:

curl -X POST https://chatmaxima.com/api/v2/media/ \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/brochure.pdf"

Response

{
  "status": "success",
  "code": 201,
  "message": "File uploaded",
  "data": {
    "media_url": "https://media.example.com/media/123/brochure.pdf",
    "media_type": "file",
    "file_name": "brochure.pdf"
  }
}

Pass media_url, media_type and file_name straight into your send request:

{
  "account_id": "g7h8i9j0k1l2",
  "contact_id": "ct_abc123",
  "text": "Here is the brochure you asked for.",
  "media_url": "https://media.example.com/media/123/brochure.pdf",
  "media_type": "file",
  "file_name": "brochure.pdf"
}

Allowed file types

Kind	Extensions
Images	jpg, jpeg, png, gif, webp
Video	mp4, mov, webm, 3gp, avi
Audio	mp3, m4a, aac, ogg, opus, wav, amr, flac
Documents	pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip

Files that a browser could run as a web page, such as HTML, SVG or JavaScript, are refused. Each channel also has its own limits on which types it shows inline, so a file may arrive as a download rather than a preview.

Errors

HTTP	Code	When it happens
400	MISSING_FILE	No file was sent in a field named file.
413	MEDIA_TOO_LARGE	The file is 10 MB or larger.
422	MEDIA_TYPE_NOT_ALLOWED	The file extension is not allowed. details.allowed lists the accepted ones.
502	UPLOAD_FAILED	The file could not be stored. Retry the request.

Authentication, plan and rate-limit errors are listed on the API overview.

Next Steps

• Send Messages API →
• Channel Accounts API →