Media messages
You can only send a text message up until 24 hours after receiving a message from the user. If you have not received a message from the user within this time, you will need to start a new conversation by sending a Template message.
Use the messages
node to send messages containing audio, documents, images, stickers, or videos to your customers.
In essence, when you send a message that includes media, you must provide either the ID of the uploaded media or a link to the media in the request body. You must also specify the type of media that you are sending: audio
, document
, image
, sticker
, or video
. When the request is received, the media is uploaded to the WhatsApp server and sent to the user indicated in the to
field.
When sending messages with media such as images, videos, or audio files, it is important to ensure that they are not heavy, as processing heavy media files at once can cause delays in transmission and lead to issues with message delivery.
For this, we suggest uploading media beforehand using the /media
endpoint and then utilizing the media_id
obtained from the response when sending messages.
By following this approach, you can ensure that the media file is processed accurately without causing any delays or latencies during send-outs.
Currently, there are two ways to send media messages with the WhatsApp Business API:
IDs (recommended) — To use an ID, you must first upload the media to obtain the ID required for the
messages
API call.Links (not recommended) — To use a link, you supply an HTTP(S) link from which the application will download the media, saving you the step of uploading media yourself. Please make sure you are using a mp4 direct link.
After you upload the media, use the returned ID for the id
field in the API call sending the media message.
Alternatively, you can provide a link
parameter pointing to the media you want to send. Currently only HTTP/HTTPS links are supported. You will need to use a link that directs to the mp4 file itself, which might not be available if using basic video platforms. Some suggested platforms that offer this type of link are Google Cloud Storage Bucket, AWS S3 Bucket, Streamable.
Either id
or link
is required, but should not be used at the same time.
Use the type
property to indicate the media asset's type (audio
, document
, image
, sticker
, or video
) and either the id
or link
property to indicate its ID (which you must generate) or location on your public server.
Example:
The samples below shows a media message with different objects such as URL
and Media ID
. A valid request body would look like this:
Sending media messages using Image URL:
Sending media messages using Media ID:
In the case of an unsuccessful response, a callback is sent to your Webhook URL even though the response will yield a message ID similar to a successful message send.
Media HTTP Caching
The Cloud API supports media HTTP caching. If you are using a link (link
) to a media asset on your server (as opposed to the ID (id
) of an asset you have uploaded to Meta's servers), you can instruct them to cache your asset for reuse with future messages by including the headers below in your server response when the asset is requested. If none of these headers are included, Meta will not cache your asset.
Cache-Control
The Cache-Control
header tells Meta how to handle asset caching. They support the following directives:
max-age=n
: Indicates how many seconds (n
) to cache the asset. The cached asset will be reused in subsequent messages until this time is exceeded, after which the asset will be requested again, if needed. Example:Cache-Control: max-age=604800
.no-cache
: Indicates the asset can be cached but should be updated if theLast-Modified
header value is different from a previous response. Requires theLast-Modified
header. Example:Cache-Control: no-cache
.no-store
: Indicates that the asset should not be cached. Example:Cache-Control: no-store
.private
: Indicates that the asset is personalized for the recipient and should not be cached.
Last-Modified
Indicates when the asset was last modified. Used with Cache-Control: no-cache
. If the Last-Modified
value is different from a previous response and Cache-Control: no-cache
is included in the response, Meta updates their cached version of the asset with the asset in the response. Example: Date: Tue, 22 Feb 2022 22:22:22 GMT
.
ETag
The ETag
header is a unique string that identifies a specific version of an asset. Example: ETag: "33a64df5"
. This header is ignored unless both Cache-Control
and Last-Modified
headers are not included in the response. In this case, we will cache the asset according to our own, internal logic (which Meta does not disclose).
Sample Response with Headers
API Reference
Send a media message
POST
https://waba-v2.360dialog.io/messages
The sample below shows multiple different objects such as audio
, document
, image
, sticker
, and video
for illustration purposes only. A valid request body contains only one of them.
Example:
Request Body
recipient_type
string
individual
to
string
wa_id
of the contact you want to message
type
string
SPECIFIC PARAMETERS
object (media ID) is returned.
The sample below shows multiple different objects such as audio
, document
, image
, sticker
, and video
for illustration purposes only. A valid request body contains only one of them.
Example:
[will be deprecated] If the WABA is registered in On-premise API
As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025. Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches.
POST
https://waba.360dialog.io/v1/messages
Request Body
recipient_type
string
individual
to*
string
wa_id of the contact you want to message
type
string
text
specific parameters
A successful response includes a messages
object with an ID for the newly created message.
The relevant object (dictionary with “id”) is nested in array which itself is in other dict.
Last updated