Media Messages

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:

Possible types: audio, document, image, sticker, or video.

You can only send a text message within the customer service window. Outside the customer service window, you will need to start a new conversation by sending a Template message.

Media IDs vs Media links

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. Please make sure you are using an MP4 direct link.

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.

When sending messages, we recommend uploading media first using the /media endpoint. Afterward, you can use media_id from the response to attach the media to your messages

By following this approach, you can ensure that the media file is processed accurately without causing any delays or latencies during send-outs.

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, and Streamable.

Either id or link is required, but should not be used at the same time.

How to send a media message

POST https://waba-v2.360dialog.io/messages

Request Body

Name	Type	Description
recipient_type	string	individual
SPECIFIC PARAMETERS	String
type	string
to	string	wa_id of the contact you want to message

Example:

Sending media messages using Image URL:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE-NUMBER",
  "type": "image",
  "image": {
    "link" : "https://IMAGE_URL"
  }
}

Sending media messages using Media ID:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE-NUMBER",
  "type": "image",
  "image": {
    "id" : "MEDIA-OBJECT-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: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

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 the Last-Modified header value is different from a previous response. Requires the Last-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

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>