Media message
A media message is a message that features some kind of media other than text, such as images, documents, or video. You can send a media message by making a POST
request to the /messages:send
Conversation API endpoint with the following payload:
{- "app_id": "{{APP_ID}}",
- "recipient": "{{CONTACT_ID}}",
- "message": {
- "media_message": {
- "url": "{{URL_TO_MEDIA}}"
}
}
}
Media message schema
A media message can take the following parameters and properties. Required parameters are marked.
url required | string Url to the media file. |
thumbnail_url | string An optional parameter. Will be used where it is natively supported. |
Note:
Not all channels support every parameter.
The following sections give examples of how card messages are rendered in each channel and specific parameter support:
- SMS
- Facebook Messenger
- MMS
- RCS
- Viber Bot
- Viber Business Messages
- Telegram
- KakaoTalk
- Apple Messages for Business
- LINE
WhatsApp channel natively supports media messages and will automatically detect what type of WhatsApp message to use.
Supported Media Types
In MediaMessage you can send the following media types:
- image: image/.jpeg, image/.png
- video: video/.mp4, video/.3gpp (Only H.264 video codec and AAC audio codec is supported with a single audio stream.)
- document: any valid document MIME type
- audio: audio/.aac, audio/.mp4, audio/.amr, audio/.mpeg, audio/.ogg + codecs=opus (base audio/.ogg not supported)
- sticker: image/.webp
Any other media type will be sent as plaintext URL.
The following image gives an example of a media message.
SMS
SMS channel supports image-based media messages natively. The following image gives an example of media messages.
Facebook Messenger
Facebook Messenger supports media messages natively for the following media types:
- image
- video
- audio
- document
The following image gives an example of a media message.
Instagram only supports image-based media messages natively.
Supported formats are: jpg
, png
, ico
, bmp
. The image size should be than 8 MB.
Note
Until Instagram enables sending other types of media beyond images, we will transcode your "Media Message" as a “Text Message” with a plain text URL that points to the document/video file.
The following image gives an example of a media message.
Apple Messages for Business
Apple Messages for Business supports image-based media messages as an attachment and Rich Link. Attachment fits better in media messages.
MMS
MMS supports media messages natively. The content of the media message will be validated when sending messages, and checked against the recommendations for MMS messages listed in the MMS documentation if you use the MMS_STRICT_VALIDATION flag.
In this message you can send the following media types on MMS channel:
- image: .jpg, .png (please observe that .jpg files have wider support on mobile devices than .png files)
- video: .mp4, .gif, .mov
- vCard (Virtual Contact File): .vcf
- PDF files: .pdf
We recommend you to keep media file sizes under 1MB as MMS providers usually use this limit.
The following image gives an example of a media message.
RCS
RCS channel natively supports Media Messages. Send a media message by specifying the URL to the media. Conversation API will automatically detect what type of RCS message to use - image or video.
The following image gives an example of a media message.
Viber Bot
Viber Bot channel natively supports media messages.
In this message you can send the following media types on Viber Bot channel:
- image: .jpeg, .png, non-animated .gif
- video: .mp4 with H264 encoding
- document: any valid document MIME type
The following image gives an example of media messages.
Viber Business Messages
Viber Business Messages supports media messages natively.
Supported image types:
- .jpg
- .jpeg
- .png
Supported document types:
- .doc
- .docx
- .rtf
- .dot
- .dotx
- .odt
- .odf
- .fodt
- .txt
- .info
- .xps
- .pdax
- .eps
- .xls
- .xlsx
- .ods
- .fods
- .csv
- .xlsm
- .xltx
Documents and media sent using media messages must be less than 200MB in size.
When sending a video media message, the following additional requirements apply:
- The
thumbnail_url
must be set. See the media message schema for more information. - The thumbnail URL can be a maximum of 1000 characters.
- The HTTP server that provides the video needs to set
Content-Length
in the HEAD response. - The video duration must be less than 600 seconds.
The following image gives an example of a media message.
Telegram
Telegram Bot channel natively supports various type of media messages.
- image: image/.jpeg, image/.jpg, image/.png
- Video: video/.mp4
- Audio: audio/.mp3, audio/.m4a, audio/.ogg, audio/.ocg
- File: application/.zip, application/.pdf
KakaoTalk
KakaoTalk supports Media messages natively.
Note
Media messages on KakaoTalk only support .png
and .jpg
image media types.
Media included in the Media message will be rejected by the channel if:
- the width is below 500px, or if the 'width:length' ratio is below 2:1, or above 3:4 or if the image dimension is not equal to [800px * 600px]
- image file format is different than JPG or PNG
- file size is bigger than 500KB or for image with dimension [800px * 600px] is bigger than 2MB
LINE
LINE channel natively supports various type of media messages.
Media file URL must be HTTPS over TLS 1.2 or later.
- Image formats: jpeg, jpg, png
Max image file size: 10MB - Video formats: mp4
Video thumbnail image is required (Tip: use a 1-pixel transparent image as the universal thumbnail)
Max video file size: 200MB
Max thumbnail image size: 1MB - Audio formats: m4a
Max audio file size: 200MB
WeChat channel natively supports various types of media messages.
- Image formats: jpeg, jpg, png, gif
Max image file size: 10MB - Video formats: mp4
Max video file size: 10MB - Audio formats: mp3/amr
Max audio file size: 2MB
Max audio duration: 60s