Media

Send images, video, audio, voice notes and documents from a URL, and download media you received.

POST/v1/sessions/<CHANNEL_ID>/messages/image
Send an image from a URL.
POST/v1/sessions/<CHANNEL_ID>/messages/video
Send a video from a URL.
POST/v1/sessions/<CHANNEL_ID>/messages/audio
Send an audio file from a URL.
POST/v1/sessions/<CHANNEL_ID>/messages/voice
Send a voice note from a URL.
POST/v1/sessions/<CHANNEL_ID>/messages/document
Send a document from a URL.
GET/v1/sessions/<CHANNEL_ID>/media/<MEDIA_ID>
Download media you received.

Send media

The gateway fetches the file from a URL you give it, uploads it to WhatsApp and sends it. You do not upload bytes to WAgate.

bash

curl -X POST "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/messages/document" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"to": "66XXXXXXXXX", "url": "https://example.com/files/menu.pdf", "caption": "This week'"'"'s menu", "filename": "menu.pdf"}'

The response is the same as for a text: id, chat_jid, timestamp and status: "server_ack".

Fields:

Field	Applies to	Meaning
`to`	all, required	recipient, as for a text
`url`	all	where the file is
`caption`	image, video, document	up to 4096 UTF-8 bytes. Audio and voice notes carry no caption
`filename`	document	up to 255 UTF-8 bytes, the name the recipient sees. Defaults to the last part of the URL path, then `document` plus an extension for its type
`mime_type`	document	for example `application/pdf`. Otherwise the type comes from the URL's Content-Type, else from the bytes

Accepted types and sizes

Route	Accepted	Largest file
`image`	JPEG, PNG	5 MiB
`video`	MP4 (H.264), 3GPP	16 MiB
`audio`	AAC, MP4 audio, MP3, AMR, Ogg. Sent as a file to play, not as a voice note	16 MiB
`voice`	Ogg Opus only. Shown as a voice note with its duration	16 MiB
`document`	any file	32 MiB

The type is read from the file's bytes, so a wrong file extension or Content-Type does not matter. The one exception is document, where mime_type or the URL's Content-Type is used first.

What the URL must be

http or https, with no username or password in it.
It must resolve to a public internet address. Every redirect hop is held to the same rule, and it may redirect at most 3 times.
It must answer 2xx within 30 seconds.

Errors

Status and code	Cause	Fix
400 `media_type_unsupported`	the file is not a type this kind can carry, for example a WebP sent as an image	convert it, or send it as a `document`
400 `media_too_large`	over the size limit for the kind	shrink it, or use `document` (32 MiB)
400 `media_fetch_failed`	the URL did not answer, answered with an error, or is not a public address	check the URL from outside your network
502 `media_upload_failed`	the upload to WhatsApp failed and nothing was sent	safe to retry
429 `gateway_busy` with `bound: "media"`	the gateway is holding as many media sends as it can	retry after `Retry-After`, which is 10 seconds
504 `send_unconfirmed`	outcome unknown; treat as possibly delivered	do not resend blindly; see Recipes

A media message counts as one message against your daily send cap, and against the sandbox allowance on a sandbox channel, whatever its size.

Download media you received

A message webhook, or a message read from a chat, carries media_id when the message has media. Download it with GET:

bash

curl -o file.bin "https://api-wagate.socialground.co/v1/sessions/<CHANNEL_ID>/media/<MEDIA_ID>" \
  -H "Authorization: Bearer <CHANNEL_TOKEN>"

The media ID is 64 hex characters, a dot and an extension.
The answer is the file's bytes, not JSON, always served as application/octet-stream as an attachment. Decide the real type from the message's type and the extension.
The response carries Cache-Control: private, no-store.
A well-formed ID that is not yours always answers 403 media_forbidden, whether it belongs to another channel, does not exist, or was removed by retention. An ID that is not in that shape answers 404 not_found.