WhatsApp

More than 1.5 billion global monthly users in over 180 countries use WhatsApp to stay in touch with friends and family, anytime and anywhere. WhatsApp offers simple, secure, reliable messaging and calling, available on phones all over the world. Now open to enterprises in early access, WhatsApp is poised to be the world’s most powerful business messaging channel.

• Channel overview
• Channel architecture
• WhatsApp API Client hosting

• Accounts

  • Access
  • Business Profile

• Capabilities

  • Content types
  • Indicators
  • Action Types
  • Structured Messages
  • Delivery Events
  • Audio
  • Location
  • Quoted Messages

• WhatsApp Message Us Button

  • Quick Setup
  • Button Attributes
  • Sample Snippet

• WhatsApp Message Templates

  • Creating Message Templates
  • Download Message Templates CSV
  • Sending Message Templates
  • Message Template Reconstruction
  • Message Template Default Fallback
• Formatting

• How to enable the channel

  • Create a WhatsApp API client
  • Sunshine Conversations Sandbox for WhatsApp

• How to start conversations

  • Outbound messaging
  • User initiated

• Passthrough API

  • Reserved Fields

Channel overview

WhatsApp is a channel that is built fundamentally on trust, safety and privacy. One of the reasons why so many people use WhatsApp is because it’s spam and advertisement free. To this day, users have only been able to receive messages from the people they care about, and WhatsApp guarantees that their messages are secure and encrypted so nobody else can have access to their conversations.

WhatsApp has now introduced an API for businesses. This means that enterprise software can be used to message customers over WhatsApp. It can be used to respond to customer service requests, to resolve urgent customer issues, to deliver timely notifications (receipts, account updates, gate changes, confirmations, etc.), to automate responses for frequently asked questions, and it can also be integrated into a CRM system to track ticket resolution and enrich customer data.

Channel architecture

WhatsApp architecture differs from other messaging channels in a major way. Instead of directly exposing a public REST API, WhatsApp requires deploying a WhatsApp API Client.

The WhatsApp API Client is similar to the WhatsApp application that runs on smartphones but it’s headless and runs in the cloud along with its database and media storage.

The WhatsApp API Client connects to the WhatsApp server using their proprietary ChatP protocol and exposes a REST API and webhooks to send & receive messages. The WhatsApp API Client enables end-to-end encryption, media storage and permanent connection to the WhatsApp network.

The WhatsApp API Client is provided by WhatsApp as a Docker image and requires a MySQL database and a storage volume to be functional.

In this early phase of development, the WhatsApp API Client components are updated every 45 days by WhatsApp and requires upgrade every 90 days. The Sunshine Conversations API shields your software from breaking changes in the WhatsApp API Client.

WhatsApp API Client hosting

When connecting WhatsApp to you can either connect your own WhatsApp API Client that you host or leverage Sunshine Conversations’ WhatsApp API Client hosting solution.

Sunshine Conversations’ WhatsApp API Client hosting options includes:

• Daily backups
• 24h monitoring
• High availability deployment

• Rapid upgrade cycle

  • Fast follow WhatsApp updates, without any code change on your side

To have access to Sunshine Conversations’ Deployments API, contact sales. If you already have access, see the Deployment Guide.

Accounts

Access

The WhatsApp Business Solution program is opening in a Limited Access capacity where WhatsApp approval is required for all businesses entering the program. WhatsApp and solution providers like Sunshine Conversations are bringing businesses onto WhatsApp slowly and thoughtfully to ultimately provide the most benefit for brands and end consumers. Fill out this form to indicate your interest in this early access program.

While you wait for approval from the WhatsApp team, you can start testing the integration by using the Sunshine Conversations Sandbox for WhatsApp.

Business Profile

You can configure key business information for each number connected to WhatsApp using our Update Integration Profile API or through the WhatsApp Integration Dashboard page in the Dashboard.

• A profile picture
• Address of business
• Description of business
• Email for business contact
• Business vertical/industry
• Business website

The business profile is shown to end users in the contact entry corresponding to the connected phone number.

Capabilities

WhatsApp supports a wide variety of capabilities as seen in the channel capabilities grid. Below is a detailed view of each capability.

Audio

Audio messages are rendered with an audio player and display the caption in a separate text message. When a file is larger than 5MB or has an extension not included in the following list: .aac, .mp4, .amr, .mp3, .opus, and .ogg it will be sent as a link; otherwise it will be rendered natively in the conversation. Moreover, if an error is detected when sending an audio message, the message will instead be delivered as a text message containing a link.

Location

Location messages are rendered as a map image of the location and include a name and address as text if they are included in the message.

Users can send location messages by using the Location button.

Quoted Messages

WhatsApp allows users to quote a specific message in a reply.

When receiving a reply, WhatsApp only includes the reference id of the quoted message. Sunshine Conversations uses this external message id to match it to a message present in the conversation history and provide the full message content within the message:appUser webhooks (example below). If the message can’t be matched or is older than 60 days, the external message id is still provided. See quoted messages for details.

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5963c0d619a30a2e00de36b8"
    },
    "version": "v1.1",
    "messages": [
        {
            "type": "text",
            "text": "Great, thanks! I'll be checking in!",
            "role": "appUser",
            "received": 1550589894.665,
            "name": "Steve",
            "authorId": "c7f6e6d6c3a637261bd9656f",
            "_id": "507f1f77bcf86cd799439011",
            "quotedMessage": {
                "type": "message",
                "content": {
                    "role": "appMaker",
                    "received": 1550589894.665,
                    "name": "Mario",
                    "authorId": "c7f6e6d6c3a437261bd9656e",
                    "_id": "55c8c1498590aa1900b9b9b1",
                    "type": "image",
                    "mediaUrl": "http://example.org/image.jpg",
                    "source": {
                        "type": "whatsapp",
                        "integrationId": "daf6e616c3a637261bd9656f",
                        "originalMessageId": "5a1c9fc63905320d87fb5ff1",
                        "originalMessageTimestamp": 1550581194
                    }
                }
            },
            "source": {
                "type": "whatsapp",
                "integrationId": "daf6e616c2a637261bd9656c",
                "originalMessageId": "5a1c9fc63905320d87fb5ff1",
                "originalMessageTimestamp": 1550581194
            }
        }
    ],
    "appUser": {
        "_id": "80215a432f196bc3b9354207",
        "conversationStarted": true
    }
}

WhatsApp Message Us Button

In order to make WhatsApp easily discoverable on your website, you can add the WhatsApp “Message Us” button plugin.

Your customers will be able to use this button to immediately start a conversation with your business on WhatsApp. When on desktop, clicking the button will bring the user to web.whatsapp.com. When using a mobile device, the WhatsApp native app will be opened on the user’s device if available, otherwise they will be taken to web.whatsapp.com.

Quick setup

In order to render the default button, you need to include the following code snippet in the page, where you would like the button to be rendered. The snippet requires, at a minimum, your WhatsApp phone number to generate the base button.

<div class="wa-message-us" number="15551234567">
    <script src="https://cdn.smooch.io/whatsapp/message-us-btn.min.js" type="text/javascript"></script>
</div>

For more advanced customizations, you can use the custom attributes that are available.

Button Attributes

If any of the optional attributes are omitted, the default value will be used.

All of the attributes above should be placed in the snippet as html attributes of the div:

<div
    class="wa-message-us"
    number="<YOUR_WHATSAPP_NUMBER>"
    label="<CUSTOM_BUTTON_LABEL>"
    pre_filled_message="<CUSTOM_PREFILLED_MESSAGE>"
    color="<teal | green | white>"
    size="<standard | compact>"
    border_radius="<VALUE_IN_PX_OR_%>"
>
    <script src="https://cdn.smooch.io/whatsapp/message-us-btn.min.js" type="text/javascript"></script>
</div>

Here are some examples of buttons with only changes to the color and size attributes:

	Standard	Compact
Teal
Green
White

Sample snippet with all attributes

<div
    class="wa-message-us"
    number="15555555555"
    label="Contact Us"
    pre_filled_message="I need help"
    color="green"
    size="compact"
    border_radius="20px"
>
    <script src="https://cdn.smooch.io/whatsapp/message-us-btn.min.js" type="text/javascript"></script>
</div>

This snippet will generate the following button, and will pre-fill the user chat input with “I need help”:

WhatsApp Message Templates

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

WhatsApp provides their own templated message mechanism. 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.

Creating Message Templates

If Sunshine Conversations manages your WhatsApp Business Account, you can use the Sunshine Conversations dashboard to create a message template.

1. Navigate to the WhatsApp Integration Dashboard page in the Dashboard.

2. Select the Message Templates tab.

3. Choose a Category from the dropdown list.

4. Create a unique Name. The name can only contain alphanumeric characters and underscores ( _ ). No other characters or whitespaces are allowed. The message template name is not customer facing; it is only used for internal purposes.

5. Choose the Language from the dropdown list. If you want to add an additional language to an existing message template, be sure to enter the same message template name in the previous step.

6. (optional) Choose a Header type from the dropdown list. Available types are Text, Image, and Document. If type Text is selected, then you must enter the Header Text.

7. Enter the Body text. Refer to the examples and guidelines provided by Facebook.

   Example of a shipping update:

   "Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}."

   Notice the {{1}} {{2}} {{3}} parameters that allow you to personalize the message being sent.

8. (optional) Enter the Footer text.

9. Select Submit.

Download Message Templates CSV

Select the Download templates (.CSV) link in the Message Templates tab of your WhatsApp Integration Dashboard page in the Dashboard to view the status of Facebook’s review of the message templates.

Sending Message Templates

WhatsApp’s Message Templates can be used to send messages via:

• the Post Message API
• the Shorthand Syntax

Post Message API

Using the Post Message API, WhatsApp Message Templates can be sent using "messageSchema" : "whatsapp" and while populating the message key using the native WhatsApp schema.

Example request

POST /v1.1/apps/{appId}/appusers/{smoochId|userId}/messages

{
    "role": "appMaker",
    "messageSchema": "whatsapp",
    "message": {
        "type": "template",
        "template": {
            "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
            "name": "hello_world",
            "language": {
                "policy": "deterministic",
                "code": "en_US"
            },
            "components": [
                {
                    "type": "header",
                    "parameters": [
                        {
                            "type": "image",
                            "image": {
                                "link": "https://image.jpg"
                            }
                        }
                    ]
                },
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "My User Name"
                        },
                        {
                            "type": "text",
                            "text": "My Agent Name"
                        }
                    ]
                }
            ]
        }
    }
}

When the messageSchema is specified, the message is automatically converted to the Sunshine Conversations schema to be stored in the conversation record. The Sunshine Conversations message schema is also used in the API response.

If Message Template Reconstruction is enabled, the content of the referenced Message Template will be set as the text of the resulting message, better reflecting the message that the user received.

Shorthand Syntax

You can easily send templated messages on WhatsApp using the Sunshine Conversations’ rich message syntax within a plain text message.

&((
    namespace=[[namespace]]
    template=[[template]]
    fallback=[[fallback]]
    language=[[language]]
    header_image/header_document/header_text=[[https://image.jpg/...]]
    body_text=[[param_1]]
    body_text=[[param_2]]
))&

namespace: The namespace within which the Message Template is defined (WhatsApp portal)

template: The name or “element_name” of your Message Template (WhatsApp portal)

language: The language of your Message Template (WhatsApp portal)

body_text: A variable in the list of parameters that will be inserted into the relevant fields in the Message Template. This can be provided as many times as the amount of variables in the template. For a template without variables, this should not be used.

header_image/header_document/header_text: The variable text or media url that will be used for the header of the message. You can’t use more than one header. For header_image or header_document, the url to the media must be provided.

fallback: Text fallback will usually be ignored, instead the message.text field in the conversation record will be populated automatically by Message Template Reconstruction using the template definition from the WhatsApp Manager. With Message Template Reconstruction disabled, the fallback text is saved to the conversation record and sent to the user’s non-WhatsApp channels.

Example with variables

&((
    namespace=[[XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX]]
    template=[[hello_world]]
    fallback=[[Welcome Bob, I’m Joe]]
    language=[[en_US]]
    header_image=[[https://image.jpg]]
    body_text=[[Bob]]
    body_text=[[Joe]]
))&

Example without variables

&((
    namespace=[[XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX]]
    template=[[hello_world]]
    fallback=[[Welcome Bob, I’m Joe]]
    language=[[en_US]]
))&

We recommend that you save several versions of your Message Template as “canned messages” or “saved agent replies” in your system so that agents can quickly customize and send these messages without typing the entirety of the syntax.

Old syntax (deprecated)

We also support the old shorthand syntax:

&[Welcome Bob, I’m Joe](XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX, hello_world, Bob, Joe)

When using this syntax to send templated messages, by default en-US will be used as the language. The language can be configured via the integration API.

Message Template Reconstruction

Message Template Reconstruction enables the conversation history stored by Sunshine Conversations to reflect the message as seen by the user, so that all the software connected to the conversation (e.g. agent software or bot platform) have the full context. Sunshine Conversations leverage the Business Management API to connects to your WhatsApp Manager an achieve the reconstruction. This is an optional process that has no impact on the end-user view on WhatsApp.

Example

Assuming that a WhatsApp Message Template is defined with the following content:

"Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}."

When a WhatsApp Template Message is sent to a user, the text stored in the Sunshine Conversations conversation depends on whether reconstruction is enabled.

Pre-Requisite

To take advantage of reconstruction, the WhatsApp integration requires a accountId and an accountManagementAccessToken to be set.

When using the Sunshine Conversations dashboard, the accountId and accountManagementAccessToken are populated automatically if your WhatsApp Business Account is managed by Sunshine Conversations or if you connect a Facebook account during the integration.

When using the deployments API, include the accountId and an accountManagementAccessToken properties in the request to the Create Integration API.

Existing integrations can be updated with the accountId and an accountManagementAccessToken properties with the Update Integration API.

The accountId refers to a WhatsApp Business Account ID, which can be found under WhatsApp Accounts in your business settings page.

See the WhatsApp Business Management API documentation for details on how to acquire an access token from your users.

Reconstruction to Text

When Sunshine Conversations receives a Message Template reference, it queries WhatsApp for the referenced Message Template and extracts its content, interpolates any specified variable, and creates a text message.

When shown in response to the Get Messages API or in message:appMaker webhooks, the message schema is that of a normal type: text message, e.g.

{
    "type": "text",
    "text": "<Content of the message template>"
}

Language Selection

The text of the message will contain one of the translations of the Message Template; The order of precedence is determined by:

1. The language.code in the message.
2. The HSM language fallback (hsmFallbackLanguage) configured via the integration API.
3. The first variation of en_* found.

Message Template Default Fallback

When reconstruction is not enabled, or if a fallback is not specified (in the case of the shorthand syntax) the resulting message will have a predefined fallback that doesn’t include the content of the Message Template, making it hard to parse the conversation history later on.

The text of the message will contain the following fallback if reconstruction is not enabled:

WhatsApp HSM (This message can only be displayed in WhatsApp)

Formatting

WhatsApp allows for basic formatting in messages. To format a message, or a part of a message, use the formatting symbols described in the following table:

How to enable the channel

Create a WhatsApp API Client

To connect WhatsApp for production usage, you first need to deploy a WhatsApp API client. Sunshine Conversations can host and manage a new WhatsApp API client or your own client using the deployments API, or you can deploy your own client following WhatsApp’s instructions. In both cases you can manage the API client using using the deployments API or the Sunshine Conversations dashboard.

Using the deployments API

1. Create the deployment using the create deployment endpoint. Call this endpoint with ‘hosting:smooch’ to deploy a new API client on the Sunshine Conversations infrastructure, or with ‘hosting:self’ to manage your own API client. If you are using the self hosted option, you will need to provide the API client’s baseUrl, username and password. In both cases, Sunshine Conversation will return a deployment_id to be used in subsequent API calls.
2. Activate your deployment using the activate deployment endpoint. This step requires a phone number and a verified name certificate which can be found in WhatsApp Account (WABA). If your self hosted API client is already activated you can skip this step.
3. Confirm the registration code received from the previous step using the confirm phone number endpoint. If your self hosted API client is already activated you can skip this step.

Connect a WhatsApp API client to an App

Once your WhatsApp API client is deployed and registered with a WhatsApp phone number, you can integrate it with your app by using the Integration API and providing the deploymentId.

Using the dashboard

Authenticate and authorize Sunshine Conversations to manage your WhatsApp account on your behalf.

Sunshine Conversations hosted

Get all your WhatsApp phone numbers using your WhatsApp Account ID.

Choose your phone number and enter the verified certificate name.

Self hosted

Fill the information needed to connect to the existing API client: The base url, the username and the password.

Deploying the API client

Proceed to connect and wait for the API client to be deployed.

Choose an activation method, SMS or phone.

Confirm the code sent by the chosen activation method.

You now have a working WhatsApp integration!

Sunshine Conversations Sandbox for WhatsApp

You can start building and prototyping with WhatsApp immediately without waiting for your number to be approved using the Sunshine Conversations Sandbox for WhatsApp. It uses a pre-provisioned WhatsApp phone number that is shared across all Sandbox users.

To enable it:

• Log into your Sunshine Conversations account and select the app you want to connect to WhatsApp.
• Select WhatsApp from the integrations directory.
• Register your phone by following our instructions.
• Send and receive messages between your phone and your Sunshine Conversations app, via WhatsApp.

Read our blog post for step-by-step instructions.

How to start conversations

Outbound messaging

To initiate a conversation with a user for which you know their phone number, you can use the Notification API. For more information on outbound messaging, consult the guide.

Initiate a conversation with a user on WhatsApp by making a request to the Notifications endpoint:

curl https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/notifications \
     -X POST \
     -d '{
         "destination": {
               "integrationId": "5e1f438bf99fb467810c0ab9",
               "destinationId": "+15145555333"
          },
          "author": {
               "role": "appMaker"
          },
          "message": {
               "type": "text",
               "text": "This is a sample notification."
          }
     }' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'

The Notification API also supports WhatsApp Message Templates. Like regular messages, templated messages can be sent to a user by making a request to the Notifications endpoint.

Send a templated text message:

curl https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/notifications \
     -X POST \
     -d '{
         "destination": {
               "integrationId": "5e1f438bf99fb467810c0ab9",
               "destinationId": "+15145555333"
          },
          "author": {
               "role": "appMaker"
          },
          "messageSchema": "whatsapp",
          "message": {
               "type": "template",
               "template": {
                    "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
                    "name": "sample_hsm",
                    "language": {
                         "policy": "deterministic",
                         "code": "en"
                    },
                    "components": [
                         {
                              "type": "body",
                              "parameters": [
                                   {
                                        "type": "text",
                                        "text": "Sample Notification"
                                   },
                                   {
                                        "type": "text",
                                        "text": "Sample Notification"
                                   }
                              ]
                         }
                    ]
               }
          }
     }' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'

Send a templated media message:

curl https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/notifications \
     -X POST \
     -d '{
         "destination": {
               "integrationId": "5e1f438bf99fb467810c0ab9",
               "destinationId": "+5145555333"
          },
          "author": {
               "role": "appMaker"
          },
          "messageSchema": "whatsapp",
          "message": {
               "type": "template",
               "template": {
                    "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
                    "name": "sample_hsm",
                    "language": {
                         "policy": "deterministic",
                         "code": "en"
                    },
                    "components": [
                         {
                              "type": "header",
                              "parameters": [
                                   {
                                        "type": "document",
                                        "image": {
                                             "link": "smooch.io/sunshine-conversations.jpg"
                                        }
                                   }
                              ]
                         },
                         {
                              "type": "body",
                              "parameters": [
                                   {
                                        "type": "text",
                                        "text": "Sample Notification"
                                   }
                              ]
                         }
                    ]
               }
          }
     }' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'

Example:

{
    "type": "whatsapp",
    "phoneNumber": "+15555555555",
    "confirmation": {
        "type": "immediate",
        "message": {
            "role": "appMaker",
            "text": "Hello there",
            "type": "text",
            "override": {
                "whatsapp": {
                    "payload": {
                        "type": "hsm",
                        "hsm": {
                            "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
                            "element_name": "hello_world",
                            "language": {
                                "policy": "deterministic",
                                "code": "en_US"
                            },
                            "localizable_params": [
                                {
                                    "default": "My User Name"
                                },
                                {
                                    "default": "My Agent Name"
                                }
                            ]
                        }
                    }
                }
            }
        }
    }
}

User initiated

Users can start a conversation with a business in two ways

• Creating a new contact in WhatsApp and using the business’s WhatsApp phone number
• Following a WhatsApp link

Creating a WhatsApp Link

You can easily create a deep link to automatically redirect user to a business in WhatsApp. The format of the deep link is as follows:

https://api.whatsapp.com/send?phone=<business-phone-number>

For more information on formatting a deep link, see the “using click to chat” documentation.

Passthrough API

The passthrough API is a way to send message types for which there is no corresponding Sunshine Conversations type. To accomplish this, the developer provides with the raw payload to send to the messaging provider’s API, and the Sunshine Conversations platform will “pass it through”.

To use the passthrough API, you first craft a valid message of any type, then you specify an additional override parameter for the channels you would like to use passthrough. Under the channel name (in this case WhatsApp), the payload field contains the exact structure of a valid WhatsApp API call to the Send Messages endpoint.

Example:

{
    "role": "appMaker",
    "type": "text",
    "text": "Hello there",
    "override": {
        "whatsapp": {
            "payload": {
                "type": "hsm",
                "hsm": {
                    "namespace": "XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
                    "element_name": "hello_world",
                    "language": {
                        "policy": "deterministic",
                        "code": "en_US"
                    },
                    "components": [
                        {
                            "type": "header",
                            "parameters": [
                                {
                                    "type": "image",
                                    "image": {
                                        "link": "https://image.jpg"
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

The above example depicts a simple override example, where the text message will render as “Hello there” on every channel except WhatsApp, where it would render a message based on the referenced WhatsApp Message Template. Note that all fields under payload in the above example (payload, hsm, namespace, etc.) are WhatsApp-specific fields, exactly as the WhatsApp API would accept them.

Reserved Fields

In order to ensure the message is correctly delivered, Sunshine Conversations will automatically set some fields in the payload for you. If you supply these fields, they will be ignored and replaced.