WhatsApp Business Messaging

Reaching the right consumer

A contact can be reached through WhatsApp if:

the contact's phone number is known
the contact has a WhatsApp account tied to that phone number
the contact has provided explicit opt-in permission to the organization to be contacted through WhatsApp

Each contact in Web1on1 corresponds to exactly one conversation. We can either post a message to an existing contact's conversation or start a new conversation with a new contact. Please review the previous Messaging to Consumers chapter for more information on outbound messaging.

Find an existing contact (by phone number)

Before reaching out over WhatsApp, we need to see if our contact exists and retrieve its conversation ID, by searching for a telephone number:

Request: GET /v2/contacts?profile.telephone=%2B441134960999

[
    {
        "conversation": "60a56a439cbf481246d9db9e",
        ...rest of contact record...
    }
]

If your automation has rights to more than one organization, you would typically also provide the organization (ID) as a query parameter. Phone numbers are stored in E.164 format; note the encoding of the '+' sign in the queried phone number (+441134960999).

If a matching record is returned, then evidently a contact with the phone number already exists: we can use the conversation ID to send him/her a message. Note that the presences array of the result record may contain an already-established WhatsApp connection.

Send to an existing contact

If the contact exists, you can send a message into the contact's conversation. Within a 24-hour window since the last consumer response, free-form messages can be sent.

Any delivery errors become part of the conversation, and are shown in the message stream.

Creating a new Contact Conversation

If you know for a fact that the new contact has a WhatsApp account tied to his/her telephone number, it's possible to create a new conversation with the customer over WhatsApp - on the condition that the consumer has explicitly opted in to receive messages over WhatsApp.

When starting the conversation over WhatsApp, the initial message (and any message therafter, until the contact replies) must be an approved WhatsApp Template message.

Also, when creating a type 'contact' conversation, a contact profile has to be provided with (for WhatsApp) at least the contact's telephone number.

Request: POST /v2/conversations

{
    "organization": "5bad2f12e91d2c331be33364",
    "type": "contact",
    "contact": {
        "profile": {
            "name": "John Johnson",
            "telephone": "+441134960999"
        }
    },
    "messages": [{
        "role": "agent",
        "text": "Your car is ready to be picked up!",
        "touchpoint": "whatsapp",
        "meta": {
            "template": "your_car_is_ready",
            "language": "en"
        }
    }],
}

When creating a new conversation, the first WhatsApp message in the conversation must be a template. More on WhatsApp templates below.

WhatsApp Message Examples

Sending a text message

Set the role to 'agent' to talk to the consumer, and set touchpoint to 'whatsapp' to ensure the WhatsApp channel is used.

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages
{
    "text": "Your car is ready!",
    "role": "agent",
    "touchpoint": "whatsapp"
}

Sending an image

Sending images to WhatsApp is no different from sending images to other consumer touchpoints: set the contentType to an image MIME type and the text to the image URL.

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages

{
    "text": "https://example.com/models/230i.png",
    "contentType": "image/png",
    "role": "agent",
    "touchpoint": "whatsapp"
}

Sending a file

Likewise, to send a PDF, use contentType application/pdf and have the text be the document URL. Provide an optional document title in the message.meta.

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages

{
    "text": "https://example.com/mb-brochure.pdf",
    "contentType": "application/pdf",
    "role": "agent",
    "touchpoint": "whatsapp",
    "meta": {
        "title": "Mercedes-Benz Brochure"
    }
}

WhatsApp Message Templates

For an overview of WhatsApp Message Templates, please read the admin guide before proceeding with the instructions below.

WhatsApp Message Templates are plain text messages that are individually approved by the WhatsApp team to ensure they do not violate the WhatsApp policies. Businesses must use message templates when first reaching out to users or when sending a message 24h after the last message from the user. This type of message is paid.

WhatsApp Message Templates must be used when starting a conversation or sending a reply 24 hours after the last message from the user. Attempting to send a normal message in these scenarios will be refused by WhatsApp, resulting in a delivery failure.

Create a WhatsApp Template

WhatsApp templates are managed in the Knowledge section for your organization. To create a message template, navigate to the WhatsApp Templates tab and click the + button.

Make sure to read about what is permitted inside WhatsApp templates.

Retrieving lists of approved templates

After a WhatsApp template is created, it's submitted to Facebook for approval. The approval status is shown in the administrator user interface. In addition, templates can be retrieved by querying the watemplates endpoint.

A list of approved templates for an organization can be retrieved by querying the watemplates endpoint using the organization ID and status; example:

Request: GET /v2/watemplates?organization=5e8493ba4d84280011860499&status=APPROVED

[
    {
        "organization": "5e8493ba4d84280011860499",
        "orgPath": "5e7cab2398d1dc0011b06de2#5e8493ba4d84280011860499",
        "displayName": "Request for actions",
        "name": "request_for_actions",
        "category": "ALERT_UPDATE",
        "components": [
            {
                "type": "BODY",
                "format": "TEXT",
                "text": "Hi {{contact.name}},\nCan you pick up your car today?",
                "buttons": []
            },
            {
                "type": "BUTTONS",
                "format": "TEXT",
                "buttons": [
                    {
                        "type": "QUICK_REPLY",
                        "text": "Yes"
                    },
                    {
                        "type": "QUICK_REPLY",
                        "text": "No"
                    }
                ]
            }
        ],
        "language": "en",
        "status": "APPROVED",
        "smoochId": "331000275193199",
        "createdBy": "5cee5182b8cbbc50c3e62e7f",
        "updatedBy": "5cee5182b8cbbc50c3e62e7f",
        "updatedAt": "2021-06-23T07:39:33.097Z",
        "createdAt": "2021-06-22T13:14:59.503Z",
        "id": "60d1e253afded685176a7a4d"
    },
    ...
]

Approved templates can be used programmatically by referencing the name and language template properties in messages.

Send a Template

WhatsApp’s Message Templates can be used to send messages via the Web1on1 API, by including the registered template's element name, and optionally the language, as message.meta variables.

A template can be applied to a message by setting the template name as meta.template.

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages
{
    "role": "agent",
    "text": "Your car is ready!",
    "touchpoint": "whatsapp",
    "meta": {
        "template": "your_car_is_ready",
        "language": "nl"
    }
}
The meta.language is optional, and defaults to the conversation- or organization language. If the template isn't available in the requested or default language, the text will be sent instead (as a regular message).

Include a document in the template header

A WhatsApp template may contain an optional header and/or footer. The header consists of a text, a document or an image.

To send a template that includes a document in the header, you need to specify either a fileId (a PDF from the organization's knowledge base) or a link in the message meta. Optionally, a title may be provided in the message.meta (defaults to the document title if applicable).

Example using a meta.fileId:

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages

{
    "text": "Here is the document you requested",
    "role": "agent",
    "touchpoint": "whatsapp",
    "meta": {
        "template": "sales_brochure",
        "fileId": "60078016e486f6077ec2a066"
    }
}

Example using a meta.link and a custom meta.title:

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages

{
    "text": "Here is the document you requested",
    "role": "agent",
    "touchpoint": "whatsapp",
    "meta": {
        "template": "sales_brochure",
        "link": "https://cht.onl/kbases/5e8349a51c238d0012ca4933/60ad68a66a230b6d6a50de9f.pdf",
        "title": "VW T-Cross sales information"
    }
}

Include an image in the template header

Instead of a document, you can also register a WhatsApp template with an image as the message heading. To supply the image at runtime, provide the (publicly accessible) image URL as meta.link when creating the message.

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages

{
    "text": "Your car is ready!",
    "role": "agent",
    "touchpoint": "whatsapp",
    "meta": {
        "template": "your_car_is_ready",
        "link": "https://placeimg.com/160/40/nature"
    }
}

Variables

Like any message in Web1on1, WhatsApp templates may contain context variables. Variables can be specified when registering the template, and their values can be supplied at runtime (when the template is used as a message).

See the chapter on Variables for more information, or read about Using variables in WhatsApp templates for more information on registration of WhatsApp templates-with-variables.

All known context variables, such as those prefixed with 'contact' or 'data', are available for use. Additional variables can be provided at runtime by specifying additional message.meta values.

Example:

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages

{
    "text": "Hi {{contact.givenName}}, your {{brand}} {{model}} with license plate {{licensePlate}} is ready to be picked up!",
    "role": "agent",
    "touchpoint": "whatsapp",
    "meta": {
        "template": "your_car_is_ready",
        "brand": "Renault",
        "model": "Kadjar",
        "licensePlate": "TN-326-G"
    }
}

Here's another example using variables in a sales brochure template that includes a document in its header:

Request: POST /v2/conversations/60a56a439cbf481246d9db9e/messages

{
    "text": "Hello {{contact.givenName}}, thank you for your interest. Here is the documentation you requested regarding {{topic}}. Please, let us know if you need more information😁",
    "role": "agent",
    "touchpoint": "whatsapp",
    "meta": {
        "template": "sales_brochure",
        "title": "VW T-Cross sales information",
        "link": "https://cht.onl/kbases/5e8349a51c238d0012ca4933/60ad68a66a230b6d6a50de9f.pdf",
        "topic": "the Volkswagen T-Cross"
        "fileId": "60078016e486f6077ec2a066"
    }
}

Happy templating!

Messaging to Consumers

On this page

WhatsApp Business Messaging

Reaching the right consumer

Find an existing contact (by phone number)

Send to an existing contact

Creating a new Contact Conversation

WhatsApp Message Examples

Sending a text message

Sending an image

Sending a file

WhatsApp Message Templates

Create a WhatsApp Template

Retrieving lists of approved templates

Send a Template

Include a document in the template header

Include an image in the template header

Variables