Messages

Use the /PHONE_NUMBER_ID/messages endpoint to send text messages, media, message templates to your customers. Learn more about the messages you can send.

EndpointAuthentication

/PHONE_NUMBER_ID/messages

(See Get Phone Number ID)

Authenticate yourself with a system user access token with the whatsapp_business_messaging permission.

Messages are identified by a unique ID. You can track message status in the Webhooks through its ID. You could also mark an incoming message as read through messages endpoint.

With the Cloud API, there is no longer a way to explicitly check if a phone number has a WhatsApp ID. To send someone a message using the Cloud API, just send it directly to the customer's phone number —after they have opted-in. See Reference, Messages for examples.

Message Object

To send a message, you must first assemble a message object with the content you want to send. These are the parameters used to create a message object:

NameDescription

messaging_product

Required.

Messaging service used for the request. Use "whatsapp".

recipient_type

Optional.

Currently, you can only send messages to individuals. Set this as individual.


Default: individual

to

type: String

Required.

WhatsApp ID or phone number for the person you want to send a message to.


See Phone Numbers, Formatting for more information.

type

Optional.

The type of message you want to send.


The supported options for beta users are:

  • text: for text messages.
  • template: for template messages. Text and media (images and documents) message templates are supported.
  • document: for document messages.
  • image: for image messages.
  • audio: for audio messages.

Default: text

text

Required for text messages.

A text object.

document

Required when type=document.

A media object containing a document.

image

Required when type=image.

A media object containing an image.

template

Required when type=template.

A template object.

audio

Required when type=audio.

A media object containing audio.

Text Object

NameDescription

body

Required for text messages.

The text of the text message which can contain URLs which begin with http:// or https:// and formatting. See available formatting options here.


Maximum length: 4096 characters

preview_url

Optional.

Set to true if you want to include a URL preview. In the message body, include your URL and make sure it begins with http:// or https://.


Default: false.


If you have used the On-Premises API, you have seen this field being used inside the message object. Please use preview_url inside the text object for Cloud API calls.

Media Object

See Get Media ID for information on how to get the ID of your media object.

NameDescription

id

Required when type is audio, document, or image and you are not using a link.

The media object ID. Do not use this field when the message type is set to text.

link

Required when type is audio, document, or image and you are not using an uploaded media ID.

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


Do not use this field when the message type is set to text.

caption

Optional.

Describes the specified document or image media.


Do not use with audio media.

filename

Optional.

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

Template Object

NameDescription

name

Required.

Name of the template.

language

Required.

Contains a language object. Specifies the language the template may be rendered in.


Only the deterministic language policy works with media template messages.

components

Optional.

Array of components objects containing the parameters of the message.

Language Object

Name Description

policy

Required.

Default (and only supported option): deterministic
The language policy the message should follow. See Language Policy Options for more information.

code

Required.

The code of the language or locale to use. Accepts both language and language_locale formats (e.g., en and en_US).


See Supported Languages for all codes.

Components Object

NameDescription

type

Required.

Describes the component type.


Values: header, body, or button. For text-based templates, we only support the type=body.

sub_type

Required when type=button. Not used for the other types.

Type of button to create. Supported values are:

  • quick_reply: Refers to a previously created quick reply button that allows for the customer to return a predefined message.
  • url: Refers to a previously created button that allows the customer to visit the URL generated by appending the text parameter to the predefined prefix URL in the template.

parameters

Required when type=button.

Array of parameter objects with the content of the message.

For components of type=button, see the button parameter object.

index

Required when type=button. Not used for the other types.

Position index of the button. You can have up to 3 buttons using index values of 0 to 2.

Parameter Object

NameDescription

type

Required.

Describes the parameter type.


Supported values: text, currency, date_time, image, document, video.


For text-based templates, the only supported parameter types are text, currency, date_time.

text

Required when type=text.

The message’s text. For the header component, the character limit is 60 characters. For the body component, the character limit is 1024 characters.

currency

Required when type=currency.

A currency object.

date_time

Required when type=date_time.

A date_time object.

image

Required when type=image.

A media object of type image.

document

Required when type=document.

A media object of type document.

Only PDF documents are supported for media-based message templates.

video

Required when type=video.

A media object of type video.

Currency Object

NameDescription

fallback_value

Required.

Default text if localization fails.

code

Required.

Currency code as defined in ISO 4217.

amount_1000

Required.

Amount multiplied by 1000.

Date_Time Object

NameDescription

fallback_value

Required.

Default text. For Cloud API, we always use the fallback value, and we do not attempt to localize using other optional fields.

Button Parameter Object

NameDescription

type

Required.

Indicates the type of parameter for the button.


Supported values: "payload" and "text".

payload

Required for quick_reply buttons.

Developer-defined payload that is returned when the button is clicked in addition to the display text on the button.


See Callback from a Quick Reply Button Click for an example.

text

Required for url buttons.

Developer-provided suffix that is appended to the predefined prefix URL in the template.

Examples

Text Messages

To send a text message, make a POST call to /PHONE_NUMBER_ID/messages and attach a message object with type=text. Then, add a text object.

EndpointAuthentication

/PHONE_NUMBER_ID/messages

(See Get Phone Number ID)

Authenticate yourself with a system user access token with the whatsapp_business_messaging permission.

Sample request:

curl -X  POST \
 'https://graph.facebook.com/v12.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "text",
  "text": { // the text object
    "preview_url": false,
    "body": "MESSAGE_CONTENT"
  }
}'

A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o",
    }]
}

Media Messages

To send a media message, make a POST call to /{phone-number-ID}/messages and attach a message object with type=image, document, or audio. Then, add a corresponding media object.

EndpointAuthentication

/PHONE_NUMBER_ID/messages

(See Get Phone Number ID)

Authenticate yourself with a system user access token with the whatsapp_business_messaging permission.

Sample request using image with link:

curl -X  POST \
 'https://graph.facebook.com/v12.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "image",
  "image": {
    "link" : "https://IMAGE_URL"
  }
}'

Sample request using media ID:

curl -X  POST \
 'https://graph.facebook.com/v12.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "image",
  "image": {
    "id" : "MEDIA_OBJECT_ID"
  }
}'

A successful response includes an object with an identifier prefixed with wamid. If you are using a link to send the media, please check the callback events delivered to your Webhook server whether the media has been downloaded successfully.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o",
    }]
}

Text-Based Message Templates

Before sending a message template, you need to create one. See Create Template Using the WhatsApp Manager for more information. If your account is not verified yet, you can use one of our pre-approved templates.

To send a text-based message template, make a POST call to /{phone-number-ID}/messages and attach a message object with type=template. Then, add a template object.

EndpointAuthentication

/PHONE_NUMBER_ID/messages

(See Get Phone Number ID)

Authenticate yourself with a system user access token with the whatsapp_business_messaging permission.

Sample request:

curl -X  POST \
 'https://graph.facebook.com/v12.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "text-string"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "DATE"
            }
          }
        ]
      }
    ]
  }
}'

A successful response includes an object with an identifier prefixed with wamid.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o",
    }]
}

Media-Based Message Templates

Before sending a message template, you need to create one. See Create Template Using the WhatsApp Manager for more information. If your account is not verified yet, you can use one of our pre-approved templates.

To send a media-based message template, make a POST call to /{phone-number-ID}/messages and attach a message object with type=template. Then, add a template object.

EndpointAuthentication

/PHONE_NUMBER_ID/messages

(See Get Phone Number ID)

Authenticate yourself with a system user access token with the whatsapp_business_messaging permission.

Sample request:

curl -X  POST \
 'https://graph.facebook.com/v12.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT-STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      }
    ]
  }
}'

A successful response includes an object with an identifier prefixed with wamid.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o",
    }]
}

Interactive Message Templates

Before sending a message template, you need to create one. See Create Template Using the WhatsApp Manager for more information. If your account is not verified yet, you can use one of our pre-approved templates.

Interactive message templates expand the content you can send recipients beyond the standard message template and media messages template types to include interactive buttons using the components object. There are two types of predefined buttons:

  • Call-to-Action — Allows your customer to call a phone number and visit a website.
  • Quick Reply — Allows your customer to return a simple text message.

These buttons can be attached to text messages or media messages. Once your interactive message templates have been created and approved, you can use them in notification messages as well as customer service/care messages.

To send an interactive message template, make a POST call to /{phone-number-ID}/messages and attach a message object with type=template. Then, add a template object with your chosen button.

EndpointAuthentication

/PHONE_NUMBER_ID/messages

(See Get Phone Number ID)

Authenticate yourself with a system user access token with the whatsapp_business_messaging permission.

Sample request:

curl -X  POST \
 'https://graph.facebook.com/v12.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer SYSTEM_USER_ACCESS_TOKEN' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

A successful response includes an object with an identifier prefixed with wamid.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o",
    }]
}