Setup

Enabling the channel

Please follow the guidance here to setup the WhatsApp channel in Dotdigital prior to attempting to send via the API.

Register template(s)

To initiate a conversation in WhatsApp you may only send a registered and approved templated message, so you should follow this guidance on how to setup a template to ensure you can send your first WhatsApp message via API.

Channel identifier

In the Enterprise Communications API this channel can be referenced using: whatsApp

This identifier can be used in the rules array, channelOptions and customBody sections.

Send a WhatsApp message

To send a WhatsApp message through the Enterprise Communications API you must ensure that:

your channel rules include the whatsApp channel
you specify either a phoneNumber in international format or a profileId with a phone number in the to section of your request.

The message itself can be of two different types.

Message types

The message type you can send is governed by whether you are in a conversation with a WhatsApp user or not. A conversation on WhatsApp is considered to be occurring for 24 hours after the last inbound message you received from a WhatsApp user.

Outside of a conversation window you can only send template messages. Within a conversation window, either template or session messages can be sent.

Template messages

If you’re not in a conversation with a WhatsApp user then you may only send a pre-approved template-based message. As part of the onboarding process we register your templates with WhatsApp for you, and provide you with the template ID's and the template namespace.

Currently, templates can only be text based and may be defined in multiple languages. Templates can also contain parameters to allow personalization and specifics to be included in the message.

Send a template message

To use the Enterprise Communications API to send a template message you must include a special message part which is used to identify the template required and pass the parameters required for that template.

Learn more in Multi-part messages.

The MIME type for the message part is whatsapp/template. As only the WhatsApp channel can use this MIME type, you must include a channel filter using the channels array and include the value whatsApp.

The following additional fields are required in the data field of the message part:

Field	Description	Example value	Required
templateName	The unique name of the template you want to send. You can find this value in the templates section for your WhatsApp channel.	dispatch_confirmation	Yes
languageCode	The desired language you want the template sent in. You must have pre-registered the language variant of the template prior to using it. Contact your Customer Success representative to do this.	en	Yes
parameters	This is the array of parameters to be merged into your template. It is important to ensure the order of the values in the array matches the order you want them merged into the template. The parameters can be of the following types: text – a string value. currency – a currency value that is localized automatically. date_time – A date time image – an image video - a link to a video document - a link to a document Include values for all the parameters in the template, ensuring the types match those you registered.For more information on parameters please see the Meta documentation here .	`[ { "type": "text", "text": "Dave" }, { "type": "text", "text": "1234" } ]`	No
components	Array of components objects containing the media elements of the message. See Send media templates section		No

🚧
Variable ordering is important
When passing parameters with your template message sends it is critical to order the parameters match those used in your template.

Parameter types

These sections give you an overview of the parameters you could pass to your templates, but for more information on parameters please see the Meta documentation here .

Text parameters

You need to includes the following fields in your parameter object:

Field

Description

Example value

Required

type

The type of the parameters

text

Yes - fixed value

text

The text value.

Character limit varies based on the following included component type:

Header component type: 60 characters
Body if other component types also included: 1000 characters
Body if single text based component: 32768 characters

My text to merge

Yes

Example

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "channels": [
        "whatsApp"
      ],
      "type": "whatsapp/template",
      "data": {
        "templateName": "dispatch_confirmation",
        "languageCode": "en",
        "parameters": [
          {
            "type": "text",
            "text": "Dave"
          },
          {
            "type": "text",
            "text": "1234"
          }
        ]
      }
    }
  ]
}

Currency parameters

In order to send a localizable currency value you need to includes the following fields in your parameter object:

Field	Description	Example value	Required
type	The type of the parameters	currency	Yes - fixed value
currency	A currency object to describe the currency value and source currency.	{ "type": "currency", "currency": { "fallback_value": "$199.99", "code": "USD", "amount_1000": "19999000" }	Yes

currency object

Field	Description	Example value	Required
fallback_value	Generic plain text representation of the date time value which is used if localization isn’t possible.	$199	Yes
currency_code	The ISO currency code your charge is based on.	USD	Yes
amount_1000	The amount to charge in one thousandths of the currency, for example, $9.99 is 9990 , worked out by 9.99 * 1000.	9990	Yes

Example

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "channels": [
        "whatsApp"
      ],
      "type": "whatsapp/template",
      "data": {
        "templateName": "dispatch_confirmation",
        "languageCode": "en",
        "parameters": [
          {
            "type": "currency",
            "currency": {
              "fallback_value": "$199.99",
              "code": "USD",
              "amount_1000": "19999000"
          }
        ]
      }
    }
  ]
}

Date/time parameters

In order to send a date time value you need to include the following fields in your parameter object:

Field	Description	Example value	Required
type	The type of the parameters	date_time	Yes - fixed value
date_time	A date_time object to describe the date and time using individual component parts.	{ "fallback_value": "February 25, 1977" }	Yes

date_time object

Field	Description	Example value	Required
fallback_value	Generic plain text representation of the date time	February 25, 1977	Yes

Example

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "channels": [
        "whatsApp"
      ],
      "type": "whatsapp/template",
      "data": {
        "templateName": "dispatch_confirmation",
        "languageCode": "en",
        "parameters": [
          {
            "type": "date-time",
            "date_time": {
              "fallback_value": "February 25, 1977"
            }
          }
        ]
      }
    }
  ],
  "metadata": {
    "data": "My correlation data"
  }
}

Image parameters

In order to send an image you need to include the following fields in your parameter object:

Field	Description	Example value	Required
type	The type of the parameters	image	Yes - fixed value
image	A media object of type image	{ "type": "image", "image": { "id": "image1", "link": "https://files.readme.io/6102a7e-dotdigital_logo_stacked_reversed_RGB.png"> } }	Yes

media object

Field	Description	Example value	Required
id	The media object ID	image1	Yes
link	The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. See here for the supported media types.	https://files.readme.io/6102a7e-dotdigital_logo_stacked_reversed_RGB.png	Yes

Example

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "channels": [
        "whatsApp"
      ],
      "type": "whatsapp/template",
      "data": {
        "templateName": "dispatch_confirmation",
        "languageCode": "en",
        "parameters": [
          {
            "type": "image",
            "image": {
              "id": "image1",
              "link": "https://files.readme.io/6102a7e-dotdigital_logo_stacked_reversed_RGB.png"
            }
          }
        ]
      }
    }
  ],
  "metadata": {
    "data": "My correlation data"
  }
}

Video parameters

In order to send an image you need to include the following fields in your parameter object:

Field	Description	Example value	Required
type	The type of the parameters	video	Yes - fixed value
video	A media object of type image	{ "type": "video", "image": { "id": "video1", "link": "https://fakesite.io/myVideo.mp4">> } }	Yes

media object

Field	Description	Example value	Required
id	The media object ID	video1	Yes
link	The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs. See here for the supported media types.	https://fakesite.io/myVideo.mp4	Yes

Example

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "channels": [
        "whatsApp"
      ],
      "type": "whatsapp/template",
      "data": {
        "templateName": "dispatch_confirmation",
        "languageCode": "en",
        "parameters": [
          {
            "type": "video",
            "image": {
              "id": "video1",
              "link": "https://fakesite.io/myVideo.mp4"
            }
          }
        ]
      }
    }
  ],
  "metadata": {
    "data": "My correlation data"
  }
}

Send media templates

If you have chosen to use media in your WhatsApp templates then to pass the additional information you must use the custom body option.

📘
The JSON you need to pass in the custom body to use a media template is described in Meta’s developer documentation.

We automatically populate the to field within the custom body block, so you don’t need to specify it.

The following example is of a call to send a media template with an image header and two parameters in the body.

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "customBody": {
    "whatsApp": {
      "type": "template",
      "template": {
        "name": "appointment_booked",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "image",
                "image": {
                  "link": "https://files.readme.io/6102a7e-dotdigital_logo_stacked_reversed_RGB.png"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "date_time",
                "date_time": {
                  "fallback_value": "2021-09-02"
                }
              },
              {
                "type": "text",
                "text": "London"
              }
            ]
          }
        ]
      }
    }
  }
}

Session messages

Session messages can be sent within a WhatsApp conversation session, which lasts 24 hours from the last inbound you received from a WhatsApp user. Session messages are designed to be used to allow businesses to send the information necessary to answer a WhatsApp user’s queries and therefore are free format.

To use the Enterprise Communications API to send a session messages you can use either the standard body field to send text-based messages, or for multimedia use multi-part messages.

Learn more in Multi-part messages.

The following message types are supported by WhatsApp:

Text, with optional URL preview.
Image (JPG, JPEG, PNG), with optional text comment.
Audio (AAC, M4A, AMR, MP3, OGG, OPUS)
Documents (PDF, DOC(X), PPT(X), XLS(X))

Text formatting

WhatsApp supports simple text formatting in text-based messages that can be used to help you communicate more effectively.

The following formatting annotations are supported:

Format	Annotation	Example
Bold	***** (Asterisk)	Your order has shipped priority
Italics	_ (Underscore)	This is an estimated delivery date
~~Strike through~~	~ (Tilde)	~~Shipping charge £10.00~~
`Code`	``` (3 x Back quotes)	`console.log("test");`

Example Session message sends

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "body": "A text session message via WhatsApp"
}

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "body": "A _formatted_ text session message via *WhatsApp*"
}

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "body": "Check out this video on YouTube: https://www.youtube.com/watch?v=oJLcwqgVOKM",
  "channelOptions": {
    "whatsApp": {
      "enableUrlPreview": true
    }
  }
}

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "type": "image/png",
      "url": "https://files.readme.io/6102a7e-dotdigital_logo_stacked_reversed_RGB.png"
    }
  ]
}

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "type": "image/png",
      "url": "https://files.readme.io/6102a7e-dotdigital_logo_stacked_reversed_RGB.png"
    },
    {
      "type": "text/plain",
      "data": "My image caption"
    }
  ]
}

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "type": "audio/mp3",
      "url": "https://sample-videos.com/audio/mp3/crowd-cheering.mp3"
    }
  ]
}

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "messageParts": [
    {
      "type": "application/pdf",
      "url": "http://cdn.dnky.co/docs/example.pdf",
      "name": "Overview.pdf"
    }
  ]
}

📘
Message length
The maximum length of a text based WhatsApp message supported is 4096 characters.

Channel options

The following additional channel options can be used to control the WhatsApp channel’s most common options.

To use the channel options, create an object with your options in the request’s channelOptions section in the whatsApp property:

Property	Type	Description
phoneNumber	string	The registered WhatsApp phone number to send the message from. Default from channel configuration is used if not specified.
enableUrlPreview	Boolean	If set to `true`, any URL's sent in a text session message have a URL preview rendered underneath.

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "body": "A text session message via WhatsApp",
  "channelOptions": {
    "whatsApp": {
      "phoneNumber": "447860041651"
    }
  }
}

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "body": "Check out this video on YouTube: https://www.youtube.com/watch?v=oJLcwqgVOKM",
  "channelOptions": {
    "whatsApp": {
      "enableUrlPreview": true
    }
  }
}

Custom body

The Enterprise Communications API automatically creates WhatsApp messages for you if you only define the body property or multi parts when sending a message, but you can override this if you use the customBody property and define a whatsApp object within it

This can be useful for accessing features in the channel we don't support in our common message format.

Details of how to create a WhatsApp business message can be found in Meta’s developer documentation.

Examples of sends using WhatsApp custom bodies:

{
  "to": {
    "phoneNumber": "447123123123"
  },
  "rules": [
    "whatsApp"
  ],
  "customBody": {
    "whatsApp": {
      "preview_url": true,
      "text": {
        "body": "You have to check out this amazing messaging service https://www.whatsapp.com/"
      }
    }
  }
}

🚧
Ensure you specify a to block
When using the customBody option with the WhatsApp channel you still need to specify the phoneNumber in the to block as this is used for profile identification.

Receipts and inbounds

Inbound messages

Allows you to receive messages sent from WhatsApp users to your hosted WhatsApp phone numbers. Messages are delivered to a URL of your choosing using the webhook system.

Receipts

If you need to to know the status of messages you've sent using one of our APIs, you can request that delivery receipts are forwarded to a URL of your choosing using the webhook system.

You can receive the following types of receipts:

Sent
Delivered
Read
Expired
Failed

Specific channel data

The WhatsApp channel carries the following extra channel specific data in the message.sent webhook event which may be of use in your integrations.

The channel data can be found in the message.sent webhook event in the payload > channelData node:

"channelData": {
    "whatsApp": {
      "virtualDeviceNumber": "447123123123",
      "isTemplateMessage": true,
      "isWithinConversationWindow": false,
      "phoneNumberCountryCode": "GB"
    }
  }

{
    "eventId": "802dd5d4-6c4b-4dc5-894b-45cb9093edc6",
    "accountId": 1234,
    "apiSpaceId": "ae1f5482-2438-41ce-ac1a-9137491f701d",
    "name": "message.sent",
    "payload": {
        "id": "0cae9944-e9cc-4e02-8b57-6b6fdda5bf83",
        "details": {
            "channel": "whatsApp",
            "channelStatus": {
                "id": "gBEGRHcVF4YFAgkZWbkNtLCDl3Q",
                "status": "sent",
                "timestamp": "1553856524"
            }
        },
        "channelData": {
            "whatsApp": {
                "virtualDeviceNumber": "447123123123",
                "isTemplateMessage": true,
                "isWithinConversationWindow": false,
                "phoneNumberCountryCode": "GB"
            }
        },
        "metadata": {
            "data": "My correlation data"
        },
        "updatedOn": "2019-03-29T10:48:44.000Z"
    },
    "revision": 3,
    "etag": "\"2e-1+NMqmJkP6uO+VSvP40vKRcl0nw\"",
    "timestamp": "2019-03-29T10:48:44.963Z"
}

The data:

Path	Field	Description
whatsApp	virtualDeviceNumber	The identifier WhatsApp is using to target the device you sent to.
whatsApp	isTemplateMessage	Boolean indicating whether the message sent was a template based message or not.
whatsApp	isWithinConversationWindow	Boolean indicating whether the message was sent within a conversation window or not.
whatsApp	phoneNumberCountryCode	The two-character country code for the phone number you sent to.