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

• WhatsApp Message Templates

  • Creating templated messages
  • Sending templated messages
• Formatting

• How to enable the channel

  • WhatsApp API Client
  • Smooch Sandbox for WhatsApp

• How to start conversations

  • Business initiated
  • 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 Smooch API shields your software from breaking changes in the WhatsApp API Client.

WhatsApp API Client hosting

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

Smooch’s WhatsApp API Client hosting options includes:

• Multiconnect setup

  • Enables a high message throughput of more than 100 message per second - much faster than SMS.

• Daily backups

• 24h monitoring

• High availability deployment

• Rapid upgrade cycle

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

To have Smooch provision your first WhatsApp API Client, contact sales.

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 Smooch 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 Smooch Sandbox for WhatsApp.

Business Profile

You can configure key business information for each number connected to WhatsApp using our Update Integration Profile API.

• 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.

WhatsApp Message Templates

WhatsApp provides their own templated message mechanism. 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 templated messages 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. Here’s an example:

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

Notice the {{1}} parameter that allows you to personalize the message being sent.

Creating templated messages

Message templates are created in the WhatsApp developer portal. When creating a desired message template element, you must have ready the following:

1. Element name

2. Text content

3. All translations desired

The message template element name can only be lowercase alphanumeric characters along with a ’_’ (underscore). No other characters or whitespace are allowed.

Sending templated messages

WhatsApp’s templated messages can be sent on Smooch in 3 ways:

• Using the shorthand syntax

• As part of a Smooch message template

• Via the API

Shorthand syntax

You can easily send WhatsApp templated messages by using the Smooch’s rich message syntax within a plain text message.

&[text_fallback](namespace, name, param_1, param_2, ...)

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

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

param_n: An ordered list of parameters that will be inserted into the relevant fields in the template

text_fallback: Text that will be sent to the user if they are not on WhatsApp and that will be saved to the conversation record.

Example

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

We recommend that you save several versions of your 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.

Message templates

Smooch lets you define rich messages templates and easily send them to users. This functionality can be leveraged to send WhatsApp own templated messages. See our complete guide on message template for more details.

API

WhatsApp message templates can be sent via the passthrough API. 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": "fallback",
						"code": "en_US"
					},
					"localizable_params": [{
						"default": "My User Name"
					},{
						"default": "My Agent Name"
					}]
				}
			}

		}
	}
}

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

WhatsApp API Client

To connect WhatsApp for production usage, you first need to deploy a WhatsApp API client. Smooch can host and manage a WhatsApp API client for you, or you can deploy your own client following WhatsApp’s instructions.

Once you have your WhatsApp API client deployed and registered with a WhatsApp phone number, you can integrate it with your Smooch App by using the Integration API.

Smooch Sandbox for WhatsApp

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

To enable it:

• Log into your Smooch 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 Smooch app, via WhatsApp.

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

How to start conversations

Business initiated

To initiate a conversation with a user for which you know their phone number, you can use the Pre-Create User API as well as the Link User To Channel API. For more information on business initiated conversations, consult the guide.

If the appUser that you would like to message on WhatsApp does not exist yet, use the pre-create user API to create one.

Example:

curl https://api.smooch.io/v1.1/apps//appusers \
     -X POST \
     -d '{"userId": "", "credentialRequired": true}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

Then, use the link user to channel API to add a WhatsApp client to the user.

Example:

curl https://api.smooch.io/v1.1/apps//appusers//channels \
     -X POST \
     -d '{"type": "whatsapp", "confirmation": {"type": "immediate"}, "phoneNumber": ""}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

If the user has a WhatsApp account, the link will succeed and a WhatsApp client will be added to the user. You can then start sending messages to the user. If the user does not have a WhatsApp account, the link attempt will fail. Your application can listen to link event webhooks to be notified when the link attempt succeeds or fails.

Example:

{
	"type": "whatsapp",
	"phoneNumber": "<some-phone-number>",
	"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": "fallback",
								"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 Smooch type. To accomplish this, the developer provides Smooch with the raw payload to send to the messaging provider’s API, and the Smooch platform will “pass it through”.

To use the passthrough API, you first craft a valid Smooch 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": "fallback",
						"code": "en_US"
					},
					"localizable_params": [{
						"default": "My User Name"
					},{
						"default": "My Agent Name"
					}]
				}
			}

		}
	}
}

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 WhatsApp templated message. 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, Smooch will automatically set some fields in the payload for you. If you supply these fields, they will be ignored and replaced.