Contact usRequest a demo

Integrating WhatsApp into Unblu

If you want to engage with your customers using WhatsApp but don’t want to give up the benefits of using Unblu—​with regard to compliance, for example—​you can get the best of both worlds thanks to WhatsApp external messengers.

Unblu’s native WhatsApp integration uses the WhatsApp Business Cloud API, which supports WhatsApp idiosyncracies such as the Standard Messaging Window and WhatsApp message templates. It also handles the status (read, delivered, retry) of messages exchanged between WhatsApp and Unblu.

With the WhatsApp external messenger, messages exchanged between your customers and your agents through WhatsApp are encrypted from the moment they leave the customer’s device until they reach the Unblu server.

Native WhatsApp integration was introduced in Unblu 8.9.2. Older versions of Unblu rely on custom external messengers and thrid-party middleware to integrate WhatsApp.

Configuring Unblu for WhatsApp

To use WhatsApp with Unblu, there are two things you must do in Unblu:

  • You must create the conversation templates you need.

  • You must configure at least one WhatsApp external messenger.

Create conversation templates for WhatsApp conversations

Depending on your organization’s use case for WhatsApp integration, you may also want to create a conversation for agents to initiate WhatsApp conversations with users.

  • When you set up a WhatsApp external messenger, you must provide the name of a conversation template to use for incoming WhatsApp chat requests. The template must have the engagement type CHAT_REQUEST or OFFLINE_CHAT_REQUEST. The latter is recommended, since you can’t configure different conversation templates for the two engagement types. Furthermore, a conversation template with the engagement type CHAT_REQUEST doesn’t work if there aren’t any agents online.

  • If you want agents to be able to initiate WhatsApp conversations, you must create a conversation template with the engagement type CHAT_INVITE. Do this after after you’ve created the WhatsApp external messenger the template should use.

    Once you’ve created the template, set com.unblu.conversation.outbound.enableOutboundConversation to true. Next, set com.unblu.conversation.outbound.outboundChannel to the WhatsApp external messenger you want conversations based on this template to use.

The text property com.unblu.conversation.message.externalMessengerTemplateAgent lets you embed the text of the agent’s message in a message. You can also automatically add the agent’s name to the text message.

Whose messages the text property is applied to depends on the configuration property com.unblu.externalmessenger.useAgentMessageTemplate.

Configure a WhatsApp external messenger

Before you start adding a WhatsApp messenger to Unblu, collect the following information from your WhatsApp Business Account:

  • Your WhatsApp Business Account ID

  • The WhatsApp phone number ID of the phone number you want the WhatsApp external messenger to use. Don’t enter the phone number itself.

  • An access token for your WhatsApp application

  • The WhatsApp application secret used to validate webhook payloads

You must also know the name of the conversation template you want the WhatsApp external messenger to use for incoming chat requests.

With this information to hand, you can create a WhatsApp external messenger using the Account Configuration interface or the Unblu Web API.

Don’t create multiple WhatsApp external messengers that use the same WhatsApp phone number ID. If you do, Unblu can’t determine which one to use when it receives a WhatsApp message and logs an error.

Language detection

If your organization services customers in multiple language regions, you probably want incoming chat request to be triaged directly to agents who speak the language a text message was written in. To this end, Unblu uses the Lingua library to detect which language the first incoming message of a conversation is written in. It calculates confidence values for the likelihood that the incoming message from an external messenger is in one of a number of languages. If the difference between the confidence values of the two most likely languages falls below a certain threshold, the default account language is used instead.

The threshold for the difference between the confidence values is set with the configuration property com.unblu.externalmessenger.sms.languageDetectionMaximumRelativeDistance.

For a list of the languages Lingua supports, refer to Which languages are supported.

Limitations

The differences in how WhatsApp and Unblu work and what they’re intended for result in a number of limitations in their interoperability.

Limitations sending messages from WhatsApp to Unblu

Some WhatsApp features aren’t available in Unblu:

  • You can’t listen to WhatsApp voice messages directly in Unblu. Rather, voice messages are uploaded to Unblu as audio files. To listen to them, users must download the audio file to their device.

  • In WhatsApp, users can react to messages. These reactions appear as emojis on the message they’re reacting to. In Unblu, such reactions appear as separate messages in the conversation.

  • WhatsApp polls aren’t supported.

Limitations sending messages from Unblu to WhatsApp

Some Unblu features aren’t compatible with WhatsApp:

  • WhatsApp only allows you to upload files no larger than 100 MB. If the value of com.unblu.filemanager.maximumUploadSize is larger than that, you still can’t upload larger files.

  • WhatsApp restricts the types of file you can upload to a conversation. For more information, refer to the WhatsApp Cloud API documentation.

  • Unblu doesn’t support all WhatsApp message template features (variables, for example). If a message template isn’t compatible with Unblu, its status appears as Active - Incompatible on the external messenger’s Message templates tab in the Account Configuration interface.

    For more information, see WhatsApp message templates below.

Markdown

Both Unblu and WhatsApp let you use Markdown in chat messages. However, there are a number of varieties of Markdown, commonly referred to as "flavors." Unblu and WhatsApp support different flavors of Markdown, and these flavors aren’t entirely compatible.

What does this mean for you and your users?

  • If someone uses Markdown in WhatsApp, Unblu doesn’t interpret the message as Markdown. It displays all the characters that were entered. For example, the message "This message contains *bold*, _italic_, and `inline code` Markdown!" looks like this in WhatsApp:

    This message contains bold, italic, and inline code Markdown!

    In Unblu, on the other hand, it looks like this:

    This message contains *bold*, _italic_, and `inline code` Markdown!

  • If someone uses Markdown in Unblu, the Markdown is sent to WhatsApp. WhatsApp interprets the Markdown as WhatsApp-flavored Markdown and displays it to the best of its abilities. This happens regardless of whether com.unblu.conversation.message.chatMessageAsMarkdownEnabled is true or not.

WhatsApp message templates

Agents can only send normal chat messages to WhatsApp conversations if a visitor sent a message with WhatsApp in the last 24 hours. If that isn’t the case, agents can only send WhatsApp message templates.

In the Agent Desk, agents can select a WhatsApp message template with the click of a button. The dialog for selecting a WhatsApp message template lists all the templates of your WhatsApp Business Account that are compatible with Unblu.

Some features of WhatsApp message templates, notably variables, aren’t compatible with Unblu. You can review the compatibility and the status of your message templates in the Account Configuration interface.

It isn’t possible to limit the WhatsApp message templates agents can select from. They can choose from all compatible active templates. If you want to prevent agents from using a particular WhatsApp message template, you must disable it the WhatsApp manager.

See also