WhatsApp

Implementation
Guide

CM.com
April 2019
V1.0
 April 2019

Content:
1 General ....................................................................................................................................................... 2
1.1 Who should read this guide? ......................................................................................................................... 2
1.2 Prerequisites.................................................................................................................................................. 2

2 Designing WhatsApp communication .......................................................................................................... 3

2.1 Notifications .................................................................................................................................................. 3
2.1.1 Getting Opt-in ........................................................................................................................................ 3
2.3 End-user experience ...................................................................................................................................... 7
2.4 Linking to your WhatsApp account ............................................................................................................... 8
2.5 Messages ...................................................................................................................................................... 9
2.5.1 Text messages ...................................................................................................................................... 10
2.5.2 Media messages ................................................................................................................................... 11
2.5.3 Location and Contact messages ........................................................................................................... 12
2.5.4 Templated messages............................................................................................................................ 13
2.6 Unsupported features ................................................................................................................................. 14

3. Service description ................................................................................................................................... 15

3.1 Authentication ............................................................................................................................................ 15
3.2 API Endpoints .............................................................................................................................................. 15
3.3 Sending messages ....................................................................................................................................... 16
3.3.1 Sending Rich Content ........................................................................................................................... 17
3.3.2 Sending Templated Messages .............................................................................................................. 18
3.3.3 Error handling ...................................................................................................................................... 19

Page | 1
 April 2019

1 General
This implementation guide can be used for the step-by-step implementation of WhatsApp messaging using
the CM.com Business Messaging API. The Business Messaging API provides your organisation with a single
API to send messages via multiple channels like SMS, WhatsApp, RCS, Viber, etc.

Information about CM’s WhatsApp solution and pricing can be found online.

Should you have any questions or need clarification, please contact CM.com on +31 (0)76 752 7000 or via
[email protected].

1.1 Who should read this guide?

This document is intended for CM customers who have purchased the CM.com Business Messaging API and
have gone through the onboarding procedures of CM.com, Facebook, and WhatsApp, and been granted a
verified WhatsApp Business Account (WABA). This document is a supplement to the available API
Documentation.

In case you haven’t gone through the onboarding procedures yet, find the WhatsApp registration form here.

1.2 Prerequisites
Before being able to send WhatsApp Messages, you need to make sure you are ready to start. CM.com will
help you configure your account. Some of these steps -like the verification of your Business Details with
WhatsApp- can take 2 weeks or more and should be taken well in advance of starting your implementation.

• Onboard your company’s information with CM.com to have it verified by WhatsApp

• Sign the CM.com contract
• Choose your Verified Name, which is the displayed name of your business account in the chat with
the end-user (Changing this later is an involved process).
• Pick a phone number to receive and send messages with. Please make sure to indicate if the number
has been used for the traditional (non-business account) WhatsApp before. If you don’t have your
own phone number, you can acquire one from CM.com.
• Inform CM.com on the URL of your application server to receive incoming messages via a webhook.

Page | 2
 April 2019

2 Designing WhatsApp communication

The use cases of WhatsApp for businesses are defined in two types of communication: notifications and the
customer care window. Both allow you to send messages, but they differ in price, features and rules and
regulations governing their usage.

The division between the two building blocks are shown in the table below.

Notifications Customer care Window

Initiative to start the Company End-users

conversation

Opt-in needed? Yes No

Message content Only Templated Messages Both Templated and Session

messages

Message components Plain text with parameters. Text, Location, Contacts, Media
(image, audio, document)

2.1 Notifications
The WhatsApp Business Solution enables companies to send notifications towards their customers,
employees, fans or any other type of end-user. Notifications are characterized by being sent outside of the
Customer Care Window and you can only use pre-defined Templated messages.

In order to send notifications, the end-users have to first give permission to these notifications by an active
‘opt-in’. This is no different from any other form of communication like SMS or Email. Failure to correctly
obtain opt-in might result in termination of your WhatsApp Business Account by WhatsApp/Facebook.

2.1.1 Getting Opt-in

These are the requirements for an opt-in:

• The opt-in has to be active, meaning it must be triggered by a user action, such as entering a phone
number or checking a box to indicate consent.
• Provide clear opt-in messaging, so the end-users know what type(s) of messaging they are signing up
for.
• Show the intended use of WhatsApp by showing the logo and name.
• Opt-in confirmation via WhatsApp after completing the opt-in process

The opt-in can be delivered to the end-users by any third-party channel (such as email, SMS, RCS, QR-Codes,
Websites). The company sending out the message is responsible for ensuring the opt-in was provided and
should register the opt-in in their system.

NOTE: Please remember that local government regulations might also apply to your ability to contact
customers.

Page | 3
 April 2019

The user must be asked to opt-in via a visual element (checkbox or similar) shown next to the WhatsApp name
and logo on your chosen third-party channel.

In addition, language must be shown adjacent to the UI elements to explain clearly what information will be
received and make specific reference to this information being sent as messages on WhatsApp, like “receive
[noun], [logo and name], on [number]"; where noun is the type of information related to the flow.

Once you have an opt-in, the validity of this opt-in is not limited to a certain time frame. You can ask for opt-in
multiple times and you should do so for situations where the purpose of the message is different from the
purpose for which an opt-in was granted.

For sending messages outside of the Customer Care Window, the flow should therefore look like this:

Page | 4
 April 2019

2.2 Customer care window

A Customer Care Window starts when an end-user reaches out to the company (sends you a message). During
this 24-hour customer care window, the company has the ability to send both Templated Messages and
Session Messages. For the duration of the Customer Care Window, Templated Messages will be billed
according to Customer Care Window pricing.

In order to activate the Customer Care Window, an end-user needs to initiate the conversation. This can be
done by any third-party channel (e.g. a button on the website with “Send Hi to +31(0)612345678 to open the
conversation” or a QR-code). The activation of the Customer Care Window by the end-users does not count as
opt-in. Therefore, it is not possible to send notifications after the Customer Care Window ended, without
obtaining a specific opt-in.

The Customer Care Window ends 24 hours after the last message is sent by the end-user. In this case, the
company loses the ability to send messages to that specific end-user and only Templated Messages for which
an opt-in has been granted can be sent.

When the company needs more than 24 hours to solve an end-user’s problem, the company has the possibility
to send a Templated Message with a resolution issue tag (outside the Customer Care Window) to trigger the
end-user to re-open the Customer Care Window. For example: “We have updates regarding your ticket {{ticket
ID}}. Please respond back if you'd like to continue support”. If the end-user responds to this notification, a new
Customer Care Window opens, enabling companies to send both Templated and Session Messages for
another 24 hours.

Page | 5
 April 2019

In practice, both building blocks (Customer Care Window and notifications) can be used within one end-user
communication flow. In the flowchart below, first a notification is sent (because the customer has approved
the opt-in), followed by the customer who activates a conversation (and therefore opens a Customer Care
Window). Because this end-user has approved the opt-in, the company has the possibility to send notifications
both inside and outside the Customer Care Window.

Page | 6
 April 2019

2.3 End-user experience

Users experience a chat with a business account like they would most other chats. For the end user, making
use of WhatsApp is free of charge, with the exception of their data usage when there is no WIFI. Hence,
consider the message size you send to your user. We strongly advise not to send files larger than 1 MB, and for
a conversation not to exceed 20MB.

Your WhatsApp Verified Name, as you have chosen during enrollment, is shown at the top of the chat. Users
can open your profile information by clicking the profile logo and/or name. This will open the business details
you specified during enrollment to the end-user.

From the same business details screen, end-users can -at any time- choose to either Block your
communication or Report your profile to WhatsApp. These are powerful actions. Once a user has blocked your
company profile, you will be unable to contact that user any longer and you have no control or appeal over
this.

Page | 7
 April 2019

When a user Reports your profile, in addition to blocking, he is filing a complaint with WhatsApp. If WhatsApp
receives significant negative feedback about your customer communications, your entire WhatsApp Business
Account can eventually be revoked.

2.4 Linking to your WhatsApp account

WhatsApp provides a short link system to initiate WhatsApp chats in the form of wa.me weblinks. These links
allow you to ask the WhatsApp iOS and/or Android app to open a chat. A WhatsApp short link looks like:

https://wa.me/15551234567

You can even provide a chat suggestion value for initiating the conversation. This suggested value will prefill
the standard “Type a message” field, ready to be sent by the user with the click of a button. Be sure to use URL
query encoding when providing the text=value.

https://wa.me/15551234567?text=I'm%20interested%20in%20your%20car%20for%20sale

You can easily incorporate such links in website buttons, Facebook campaigns or inside a QR code to target
offline distribution.

Page | 8
 April 2019

2.5 Messages
Within WhatsApp there are multiple message types available:

Message Type Communication Type Customer care window

required

A text message Session message Yes

A media message Session message Yes

A location message Session message Yes

A contacts message Session message Yes

A templated message Templated message No

Within the CM.com Business Messaging API, these types are used in ‘Conversation items’ which in turn are
used inside of a ‘Conversation’. Please find the details in our API documentation.

Page | 9
 April 2019

2.5.1 Text messages

Text messages are and should always be encoded in UTF-8 and support characters like emojis.

WhatsApp even allows for limited formatting in messages. To format all or part of a message, use these
formatting symbols:

Formatting Symbol Example

Bold Asterisk (*) Your total is *$10.50*.

Italics Underscore (_) Welcome to _WhatsApp_!

Strike-through Tilde (~) This is ~better~ best!

Code Three backticks (```) ```print 'Hello World';```

A web link is not a message type in its own right, but a piece of textual content. Links are automatically
detected, and the first link can be turned into a link preview. Links are possible in text messages and in
templated messages.

To determine the content that WhatsApp will present for a web link preview, your webpages have to
implement the Open Graph Protocol. This protocol is used by WhatsApp, Facebook, Twitter and many other
websites in the world to dynamically create previews of links.

Page | 10
 April 2019

2.5.2 Media messages

The following media types are supported by WhatsApp

Media Supported File Types

document PDF, DOC(X), PPT(X), XLS(X)

image JPG, JPEG, PNG

audio AAC, M4A, AMR, MP3, OGG OPUS

When a media message is sent, the media is stored encrypted on the WhatsApp servers for 7 days. If a user
makes a request to download the media after 7 days, the WhatsApp servers will request the same media file
from the WhatsApp Business API client. If the media has been removed, the user will be notified that the
media is unavailable. It is not safe to assume the media was downloaded simply based on the delivered and
read receipts. Outgoing media is generally safe to be removed past 30 days, but you should employ a strategy
that best suits your business.

Page | 11
 April 2019

2.5.3 Location and Contact messages

A location will deliver a bubble to the user which can be opened in a map view. It will show a marker on the
map, the address if provided, and you can accompany the marker with a small title for this marker. This type of
message is ideal if you need to provide directions to a consumer.

A contacts message will deliver a bubble with a name card. Within this name card you can provide all the
details of a person like with other vCard systems. You can either immediately contact this person via
WhatsApp or open the card and add the details to an entry in the address book of your iOS or Android device.
Please do consider any GDPR or similar privacy-related regulation.

Page | 12
 April 2019

2.5.4 Templated messages

A templated message is the only message type you can use to deliver Notifications outside of the Customer
Care Window. A templated message is a special type of message, which makes use of a predefined Message
Template. All templates need to be submitted to CM.com for pre-approval by WhatsApp before you can make
use of them. This process (at this moment) can take up to a week, so be sure to timely submit your templates.

Once a template is approved, you will receive the namespace and the ID of the template from CM.com. The
namespace and ID are references to your WhatsApp Business account and your templates within this account.
You need to refer to these identifiers when sending your templated message.

What does a Message Template look like?

A message template may consist of text, emoji or WhatsApp-specific formatting. A templated message can
consist of a maximum of 4096 characters. To personalize the message, you can use the numbered
placeholders {{x}}. Each of those placeholders can be filled with letters, digits, special characters, and spaces.
URLs can be sent, but you cannot use Media or Location items in your templates.

This is best explained with an example.

Hello {{1}}, thanks for your order! We will let you know when your order is ready to be shipped. You
can track your order with number {{2}} here {{3}}. Enjoy your day!

{{1}} = Sophie
{{2}} = 771663
{{3}} = https://yourparceldelivery.com/track/

As WhatsApp Business is intended as a customer service channel, sending advertising, marketing, and
promotional messages are prohibited, resulting in disapproval of message templates with such character. For
further information on the commerce policy, please click here.

Page | 13
 April 2019

How to register new Message Templates

To register your own Message Templates, you need to provide a template name, template tag and template
message with parameters and submit them to [email protected].

• Template name: You need a unique name to identify the template’s use case for your business.
All in lower case and without spaces. Underscore is allowed. Example: order_confirmation.
• Template tag: Select the type of message from a predefined set. Available are: Account Update,
Alert Update, Appointment Update, Issue resolution, Payment Update, Personal Finance
Update, Shipping Update, Ticket Update, Transportation Update.
• Template message with parameters: This is the actual transactional notification, which should
contain at least one parameter as placeholder, noted as {{1}}.

2.6 Unsupported features

There are several features that are currently NOT possible within WhatsApp and/or Business Messaging.

Not supported at this time are:

• Voice and video calling

• Receiving and sending Speech messages
• Receiving and sending WhatsApp stickers
• Sending Video messages (alternatively, you can send a link to a video)
• Typing indicators
• Delivered and Read indicators
• Group conversations

Page | 14
 April 2019

3. Service description

In order to send and receive WhatsApp messages you will need to integrate with the CM.com Business
Messaging API. The Business Messaging API allows you to send various message types over multiple channel
types, like SMS, WhatsApp, RCS or Viber. Detailed documentation about the API can be found in our online
API documentation.

The second part of your implementation is receiving incoming messages from customers. You have two
options for receiving messages.

• Make use of CM.com’s Customer Contact web app. Your package includes three free user
subscriptions for this service.
• If you wish to handle all incoming messages yourself, you have to implement a webhook which listens
for these incoming messages. Detailed documentation can be found in the Webhook documentation.
Your CM customer success manager will configure your webhook in the CM.com platform.

3.1 Authentication

All requests require your product token which, as a registered user, you can find on our platform in
the Gateway app. It was also e-mailed to you after registration and has a format like: 00000000-0000-0000-
0000-000000000000.

NOTE: Your product token is private information and should never be incorporated into webpages and/or
mobile applications where it can be exposed to 3rd parties.

3.2 API Endpoints

Our API supports sending messages via HTTP. You can send a POST request containing a JSON body as
specified in the documentation.

Our global gateway is accessible via one endpoint which we are load balancing over 2 platform locations in
The Netherlands. To reduce latency, and/or be compliant to local legislation we also have platforms in London,
South Africa, and Shanghai. More information can be found in our Help Center.

• Global Endpoint URL: https://gw.cmtelecom.com/v1.0/message

• South African Endpoint URL: https://gw.cmtelecom.co.za/v1.0/message
• Shanghai Endpoint URL: https://gw.cmtelecom.cn/v1.0/message
• London Endpoint URL: https://gw-uk.cmtelecom.com/v1.0/message

In order to send WhatsApp messages, be sure to specify the “allowedChannels”: [“WhatsApp”] parameter in
your JSON message.

Page | 15
 April 2019

3.3 Sending messages

Each request involves POST’ing a JSON object like this:

"messages": {
"authentication": {
"producttoken": "00000000-0000-0000-0000-000000000000"
},
"msg”: []
}

You specify your authentication token for each request and within the request you can send multiple
messages. Each individual message is a JSON object to be added inside the msg array.

For each Message Object you specify the To, From, Body/Content and, very important, the Channel via which
the message should be delivered.

{
"allowedChannels": [ "WhatsApp" ] ,
"from":
The contents of a msg"CM.com",
can however exist as multiple parts to be delivered.
"to": [{
"number": "00447911123456"
}],
"body": {
"content": "This is a simple message"
}
Error handling
}

A single Message Object inside the msg Array can actually be sent to multiple recipients but the content for
each of these recipients will be the same. If you want to send different content you need multiple message
objects or multiple requests.

This example is the most basic implementation and works for each type of Channel from WhatsApp to SMS.

Page | 16
 April 2019

3.3.1 Sending Rich Content

When sending richer messages than a simple text message, you will need to specify your contents in the Rich
Content block. The Rich Content block can be used to include the richer message types of the Business
Messaging API channels. In the case of WhatsApp, we will use it to specify multiple “Conversation Items”
inside the Conversation array.

{
"allowedChannels": [ "WhatsApp" ],
"from": "CM.com",
"to": [{
"number": "00447911123456"
}],
"body": {
"content": "This is a fallback value"
},
"RichContent": {
"conversation": []
}
}

A conversation item object contains either a “text”, a “media”, a “template” or a “location” item. This example
shows 3 conversation items, to be delivered at once to the recipient.

[
{
"text": "Hi this is a rich content message!"
},
{
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-
nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpg"
}
},
{
"location": {
"latitude": "51.603802",
"longitude": "4.770821",
"label": "CM HQ",
"searchQuery": "Konijnenberg 30"
}
}
]

Note: There are other types of conversation items that can be used for different Channel types.

Page | 17
 April 2019

3.3.2 Sending Templated Messages

A templated message is also a type of conversation item. Templated messages require you to register a
Template and get it pre-approved by WhatsApp. Please note Chapter 2.5.4 Templated messages, on how to
register your WhatsApp templates. Sending a templated message (msg) looks like this:

{
"allowedChannels": [ "WhatsApp" ],
"from": "CM.com",
"to": [{
"number": "00447911123456"
}],
"body": {
"content": "This is a fallback value"
},
"RichContent": {
"conversation": [{
"template": {
"whatsapp": {}
}
}]
}
}

Here we specify an array of a single conversation item. The item is a template type item. The template uses a
“whatsapp” template. The value assigned to the whatsapp attribute is the actual template call.

"conversation": [{
"template": {
"whatsapp": {
"namespace": "yournamespace",
"element_name": "yourtemplatename",
"language": {
"policy": "fallback",
"code": "en_US"
},
"localizable_params": [{
"default": "Name"
}, {
"default": "Order"
}, {
"default": "Order2"
}, {
"default": "https://example.com"
}
]
}
}
}]

The format of the object for the whatsapp attribute is exactly the same as the hsm object in WhatsApp’s
Official template usage documentation.

Page | 18
 April 2019

3.3.3 Error handling

It is very important to implement error handling when sending messages. Your request can succeed
completely, fail completely, or fail partially. If you send a request with multiple message objects inside the msg
array, one may fail and others might succeed. A partial failure like a complete success will respond with HTTP
status code 200, but the JSON response will help you determine that it was only a partial success.

This example shows such a situation. The response indicates a partial failure with errorCode 201. The
messages array reflects the results of each of the two messages you attempted to send in a single request. The
first message succeeded and therefore has a messageErrorCode of 0. The second message failed and reports
error code 304.

{
"details": "Created 1 message(s)",
"errorCode": 201,
"messages": [
{
"to": "00447911123456",
"status": "Accepted",
"reference": "your_reference_A",
"parts": 1,
"messageDetails": null,
"messageErrorCode": 0
},
{
"to": "00447911123457",
"status": "Rejected",
"reference": "your_reference_B",
"parts": 0,
"messageDetails": "A body without content was found",
"messageErrorCode": 304
}
]
}

A full list of error codes and their meaning is provided in the online documentation.

3.4 Receiving messages

In order to receive incoming messages when you are not using CM.com’s Customer Contact web app, you
have to implement a webhook. The documentation for the webhook for incoming messages, also known as
inbound or MO messages, can be found online.

You need to provide CM with a web address. CM will POST a JSON message to this address. If your system
replies with HTTP status code 200, you indicate receipt of the incoming message.

Page | 19