Media Messages

Use the media node to upload, retrieve, or delete media.

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.

If the WABA is registered in On-premise API

Send Media Message

POST https://waba.360dialog.io/v1/messages

You can send a message using the /v1/messages endpoint.

Headers

Name	Type	Description
D360-API-KEY	string	360dialog API KEY

201 Message sent

{
    "messages": [
        {
            "id": "x"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.35.4"
    }
}

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:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio" | "contact" | "document" | "image" | "location" | "sticker" | "text" | "video",
  
  "audio": {
    "id": "your-media-id",
  }
  
  "document": {
    "id": "your-media-id",
    "caption": "your-document-caption-to-be-sent",
    "filename": "your-document-filename"
  }
  
  "document": {
    "link": "the-provider-name/protocol://the-url",
    "provider": {
        "name" : "provider-name"
    },
    "caption": "your-document-caption"
  }
  
  "document": {
    "link": "http(s)://the-url.pdf",
    "caption": "your-document-caption"
  }
  
  "video": {
    "id": "your-media-id",
    "caption": "your-video-caption"    
  }
  
  "image": {
    "link": "http(s)://the-url",
    "provider": {
        "name" : "provider-name"
    },
    "caption": "your-image-caption"
  }
  
  "image": {
    "id": "your-media-id",
    "caption": "your-image-caption"
  }
  
  "sticker": {
    "id": "your-media-id"
  }
  
  "sticker": {
    "link": "http(s)://the-url",
    "provider": {
      "name" : "provider-name"
    }
  }
}

If the WABA is registered in Cloud API

Send a media message

POST https://waba.360dialog.io/message

Request Body

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

201: Created

Object (media ID) is returned.

{
  "id":"<MEDIA_ID>"
}

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:

{
  "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.