WhatsApp Vonage

To make it easy for your consumers to make purchases and get answers to questions using WhatsApp, the messaging channel they already use every day, Druid authors can integrate Druid chatbots with WhatsApp. This way, customers will be able to start a conversation with your chat bot in WhatsApp.

The Druid ChatBot Platform provides the WhatsApp channel via the integration partner Vonage.

Important!  The Welcome flow will be triggered at the user's first conversation with the bot; the predict with the initial "user says" is dropped.

This section describes how to connect your Druid chatbot with your Nexmo account.

Prerequisites:

  • You built and published a Druid chat bot.
  • For DRUID on premise deployments, make sure that you provide access to/from the necessary messaging endpoints as follows:
    • Outbound api.nexmo.com
    Inbound

    DRUID.BotApp

    DRUID.BotApi

To connect your Druid chatbot with your Vonage account, follow there steps:

Step 1. Get authentication details

Note:  If a JSON Web Token (JWT) was provided to you upon Vonage account creation, you will use it to authenticate your requests; skip this step.

Step 1.1. Log into your Vonage Dashboard

In your browser go to https://ui.idp.vonage.com. The Login page appears.

Enter your Vonage Dashboard credentials (email and password) and click Log in.

Step 1.2. Get API key and secret

When you create a Vonage account, an API key and secret will be created for you. To get these two values, in the Vonage Dashboard, from the BUILD & MANAGE menu, click API Settings.

Write down or copy/paste in a document the API key and API secret, you will need them to activate the WhatsApp channel in Druid.

Step 1.3. Generate JWT token for WhatsApp PROD environment using WhatsApp Messages API version v1

Important!  If you operate in a WhatsApp PROD environment using WhatsApp Messages API version v1, you must generate a JWT token for your Vonage application because authenticating using the API Key and secret is not working.

To generate a JWT token, follow these steps:

  1. Access https://developer.vonage.com/en/jwt.
  2. Provide the following parameters:

    • Your application's private key (copy it from the downloaded file during application creation).

    • The application_id.

    • Valid For field: Enter or select the duration for which the JWT token will be valid.

Step 2. Activate the WhatsApp Channel

  1. In the Druid ChatBot Portal got to your bot settings. Click the Channels tab, then click WhatsApp (by Vonage). The WhatsApp (by Vonage) Channel Info section expands.

  2. In the WhatsappNumber field, enter the phone number associated with your Vonage account, without the “+”. To get the number, in the Vonage Dashboard, from the TROUBLESHOOT & LEARN > Developer Tools menu, click Messages Sandbox. Click the WhatsApp channel and copy the phone number.

  3. In the URL field, enter the URL from your Vonage Dashboard:
    • For Vonage production environments use https://api.nexmo.com/v1/messages
    • For Vonage sandbox environments use https://messages-sandbox.nexmo.com/v1/messages

  4. Based on your Vonage account authentication method, select the Authentication Type and enter the required information as follows:
    • If you have a JWT from Vonage, select JWT Token and in the VonageWhatsappJwtToken field, enter the JWT provided to you by Vonage.

    • If you operate in a WhatsApp PROD environment using WhatsApp Messages API version v1, select JWT Token, and enter the generated token (Step 1.3.) into the VonageWhatsappJwtToken field.
    • If you have an API key and secret, select API Key & API Secret and in the two fields which appear enter the API key and secret you got at Step 1.2.

  5. Click the Publish button. The channel activation might take up to 1 minute. When the channel activation completes, the Inbound URL and Status URL fields are automatically filled in. Copy the two values, you will need them at Step 3.

    6. After the channel's activation, the following fields are available in DRUID:

    • [[ChatUser]].ChannelId = "nexmo-whatsapp"
    • [[ChatUser]].UserId - Stores the user's phone number.
    • [[ChatUser]].ChannelBotIdentifier - Stores the bot number through which a user message arrived. This field is available in DRUID 8.3 and higher.
    • [[HelpdeskClient]].PhoneNumber - Stores the user's phone number if the user engages with a helpdesk agent in a live chat. It will enable the agents to send WhatsApp Message Templates.
  6. Click Save & Close to save the WhatsApp channel configuration.

Step 3. Set up your Vonage account

In the Vonage Dashboard, from the TROUBLESHOOT & LEARN menu, click Messages Sandbox.

From the Message API version drop-down, select the desired version.

Note:  Use the WhatsApp Messages API version v1 to render interactive messages. This way you provide a better end-user experience and streamline the interactions with your clients / users, which can lead to better engagement and response rates. Interactive messages provide users with a simplified way to make a selection from multiple options or from a menu.
Important!  If you're changing the Message API Version for a bot that has the WhatsApp Channel activated, you should provide the new URL in Druid channel configuration (see Step 2); otherwise, the chatbot will NOT respond to users chatting in the WhatsApp channel.

In the Webhooks section, enter the Druid endpoints copied at Step 2 and click the Save webhooks button.

You can now test the WhatsApp channel.

Step 4. Associate multiple phone numbers to the same bot (optional)

Note:  Bot support for multiple phone numbers is available in DRUID 8.3 and higher.

Prerequisite: You need to have multiple accounts, each with an unique WhatsApp number. For more information on managing WhatsApp numbers, see Vonage documentation, section “WhatsApp Number Hosting”.

To associate multiple WhatsApp phone numbers to the same Vonage application, in Vonage developer portal, on the BUILD & MANAGE menu, click Applications and select the application you connected to the DRUID bot. Click on the Link external accounts tab and link the desired accounts.

Step 5. Test the integration

You have two options to test the integration:

From Druid

To open the chatbot in WhatsApp, in the Druid Portal, go to the bot settings, click the Channels tab and click on the WhatsApp channel icon. You can start talking to the bot.

From Vonage

Return to Vonage Dashboard and click the WhatsApp link.

Follow the Web WhatsApp and send the passphrase message filled in automatically for you in the input area.

You are now connected with your Druid chatbot in the WhatsApp channel.

Note:  In DRUID 7.5 and higher, when a user initiates a conversation with the bot, the Welcome flow will be automatically triggered. Regardless of the user's subscription status to the bot channel, the welcome message will be promptly sent to the user, ensuring a seamless and engaging interaction experience.
Note:  If the same chat user sends messages to multiple phone numbers associated to the same bot, different conversation IDs will be generated for each phone number. This ensures that each ChannelBotIdentifier corresponds to a unique ConversationId.

Receiving and Processing Voice Messages

DRUID currently supports audio messages only through Microsoft Cognitive Services. It supports all languages available in the Azure Speech Service. For a complete list of supported languages, refer to Language and Voice Support for the Speech Service.

Here's how it works:

  1. Receive audio messages. When a user sends an audio message via WhatsApp, the bot will:
    • Process the audio recording using Azure Speech resources configured in channel settings.
    • Recognize the language for Speech-To-Text (STT) based on the user's language ([[ChatUser]].Language).
    • Log in the Conversation History the user message type as 'Audio Recording'.
  2. Process audio. The bot:
    • Converts the audio message to text using Microsoft Cognitive Services.
    • Uses the converted text to predict the next conversational step.
  3. Respond. By default, the bot will respond to voice messages with text. You can choose the bot to reply with voice.

To enable voice messages support, follow these steps:

  1. In the channel configuration page, tap on Support voice messages.
  2. Enter your MS Azure Speech API key and select the region.
  3. By default, the bot replies with text. To have the bot respond with voice, toggle on Reply with voice messages.
  4. In the table, click the plus icon. A row is added to the table.
  5. From the Language drop-down, select the bot language (default or additional) and from the Voice drop-down, select the human-like neural or standard voice the chatbot will use to respond to the user.
  6. Click the Save icon displayed inline. You can add more languages and different voices per language as best suits your needs.

  7. If the channel has not been published yet, click Publish.
  8. Click the Save button at the bottom of the page to save the bot configuration.

Enable your bot to process voice messages on WhatsApp by configuring and activating the native Voice (MS Cognitive Service) channel.

Note:  The bot responds to voice messages with text only.
Related Topics Link IconRelated Topics