Sending Media Messages

/v1/messages

Use the messages endpoint to send messages containing audio, images, or documents to your customers.

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, image, document, 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.

This document covers:

Prerequisites

Request

After you upload the media with an API call to the media endpoint, use the returned ID for the id field. Alternatively, you can provide a link parameter pointing to the media you want to send. Currently only HTTP/HTTPS links are supported. Either id or link is required, but should not be used at the same time.

POST /v1/messages
{
  "recipient_type": "individual" | "group",
  "to": "whatsapp-id" | "whatsapp-group-id",
  "type": "audio" | "contact" | "document" | "hsm" | "image" | "location" | "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"
    }
  
  "video": {
    "id": "your-media-id",
    "caption": "your-video-caption"    
  }
  
  "image": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-image-caption"
    }
}

The above sample shows different objects such as audio, document, and video for illustration purposes only. A valid request body contains only one of them.

Parameters

NameRequiredDescription

recipient_type

No

Options: individual (default), group
Determines whether the recipient is an individual or a group
Specifying recipient_type in the request is optional when the value is individual. However, recipient_type is required when using group. See the Sending Group Messages documentation for more information.

to

Yes

When recipient_type is individual, this field is the WhatsApp ID (phone number) returned from contacts endpoint. When recipient_type is group, this field is the WhatsApp group ID.

type

Yes, when type is image, audio, document, video.

Options: text (default), image, audio, document, hsm, video
For text messages, see the Sending Text Messages documentation for more information. For Message Temaples, see the Sending Message Templates documentation for more information.

audio

Yes, when "type": "audio"

The media object containing audio

document

Yes, when "type": "document"

The media object containing a document

image

Yes, when "type": "image"

The media object containing an image

video

Yes, when "type": "video"

The media object containing a video

The audio, document, image, and video objects

NameRequiredDescription

id

Yes, when type is image, audio, document, or video and you are not using a link
Forbidden for "type:" "text"

The media object ID, which is returned when the media is successfully uploaded to the WhatsApp Business API Client with the media endpoint.

link

Yes, when type is image, audio, document, or video and you are not using an uploaded media ID
Forbidden for "type:" "text"

The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.

caption

No

Describes the specified image, video, or document media. Do not use with audio media.

filename

No

Describes the filename for the specific document. Use only with document media.

provider

No

This path is optionally used with link when the HTTP/HTTPS link is not directly accessible and requires additional configurations like a bearer token. For information on configuring providers, see the Media Providers documentation.

Response

The successful response includes a messages object with a message ID.

{
  "messages": [{
    "id": "gBEGkYiEB1VXAglK1ZEqA1YKPrU"
  }]
}  

An unsuccessful response will contain an error message. See Error and Status Codes for more information on errors.