Send Media Messages

Send image, video, audio and document messages by public link or by uploaded media ID.

Last updated 05 Aug 2026

Image, video, audio and document messages all share the same request shape. Set type to the media kind you are sending, then provide a matching object under that same key.

Endpoint

POST /messages.php

Request body

Field	Type	Required	Applies to	Description
`to`	string	yes	all	Recipient's phone number, same format as Send a Text Message.
`type`	string	yes	all	One of `image`, `video`, `audio`, `document`.
`<type>.id`	string	one of `id`/`link`	all	A media ID previously returned by Upload Media.
`<type>.link`	string	one of `id`/`link`	all	A public HTTPS URL Meta can fetch the file from.
`<type>.caption`	string	no	image, video, document	0-1024 characters. Not supported for audio.
`<type>.filename`	string	no	document only	1-240 characters, shown to the recipient as the file name.

You must provide exactly one of id or link - never both, never neither. If you use link, it must resolve to a real https:// URL; Meta fetches the file directly from that URL when the message is sent.

Example: image by link

curl -X POST "https://riffrechat.com/api/v1/messages.php" \
  -H "Authorization: Bearer rf_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "type": "image",
    "image": {
      "link": "https://example.com/images/product.jpg",
      "caption": "Our best seller"
    }
  }'

Example: document by uploaded media ID

{
  "to": "919876543210",
  "type": "document",
  "document": {
    "id": "1234567890",
    "caption": "Your invoice for order #1042",
    "filename": "invoice-1042.pdf"
  }
}

Example: video by link

{
  "to": "919876543210",
  "type": "video",
  "video": { "link": "https://example.com/videos/demo.mp4", "caption": "How it works" }
}

Example: audio by link

Audio messages do not support a caption:

{
  "to": "919876543210",
  "type": "audio",
  "audio": { "link": "https://example.com/audio/note.ogg" }
}

Success response

Same shape as Send a Text Message: 202 Accepted with queue_id, status, status_label, charged, currency, balance_after, message_id and internal_queue_id.

Errors specific to media messages

`error` slug (varies by type)	Cause
`image_must_contain_exactly_one_of_id_or_link`	Neither, or both, of `id`/`link` were supplied. Slug name changes per type, for example `document_must_contain_exactly_one_of_id_or_link`.
`image_link_must_be_a_valid_https_url`	`link` is not a valid `https://` URL.
`media_caption_must_contain_between_0_and_1024_characters`	`caption` exceeds 1024 characters.
`document_filename_must_contain_between_1_and_240_characters`	`filename` is empty or exceeds 240 characters.

To send a local file instead of a public link, upload it first with Upload Media and pass the returned id here.

Riffre API Reference