WhatsApp Meta

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 Meta integration (direct integration).

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.

Prerequisites

  • You built and published a DRUID chat bot.
  • You have a Meta Developer account.
  • For DRUID on premise deployments, make sure that you provide access to/from the necessary messaging endpoints as follows:
    • Outbound graph.facebook.com 
    Inbound DRUID.BotApp

To integrate a DRUID chatbot with WhatsApp via Meta, follow these steps:

Step 1: Create Meta developer app

Note:  The Meta UI may appear slightly different depending on which version you are using.
Hint:  If you already have an app, skip this step, go to Step 2.
  1. In your browser, navigate to Meta for Developers and log in.
  2. On the toolbar, click My Apps. Your Apps page appears.
  3. Click the Create App button.

    4. The Create an app wizard appears.

  4. Enter App name and your email address (the email address Meta will use to contact you about your app).

  5. Click Next.
  6. Select Other use case and click Next.

  7. Select Business as app type and click Next.

  8. Select your Business portfolio and click Create app.

  9. For security reasons, re-enter your password and click Submit.

  10. Find the WhatsApp product and click Set up. The WhatsApp Quickstart page appears.
  11. Click Start using the API to test message sending in the WhatsApp channel.
  12. Click the Generate access token button.
  13. Follow the on screen instructions to grant the app access to manage your WhatsApp account and manage and access conversations in WhatsApp.
  14. Select your test phone number in the From field. (Unless you have registered other phone numbers, this will be the only phone number in From).
    15. Note:  When you’re ready to use your app for a production use case, you need to use your own phone number to send messages to your users.
  15. Enter the phone number you would like to message in the To field. Ensure the number is correct, and that you want to add it to your list of 5 possible message recipients — as you add phone numbers, follow the prompts on the screen to verify you have access to them. Once this number has been added, it cannot be removed from your list.
    16. Note:  This limitation is only for WhatsApp-provided test phone numbers. Real phone numbers that you register do not have a limit on the number of recipients.

  16. Once you enter a recipient phone number, the code sample on the page will be updated to demonstrate an API call that sends a test message to that number.

  17. Click Send message to send the first message. Alternatively, you can copy the code sample provided and execute it in your Terminal or in Postman. You have just sent a test message!

Step 2: Generate permanent token for your app

To generate a permanent token for your app in Business Manager, you must add an admin user with full control for your app (asset).

Follow these steps to generate the permanent token:

  1. Go to Business Settings.
  2. On the Users menu, click System users.

  3. In the System users page, click the Add button.

  4. Enter a name for the system user, and from the System user role field, select Admin. Then, click Create system user.

    5. The admin user access page appears. Now you have to assign the admin user assets such as your app.

  5. Click on the actions icon at the top right corner of the page and select Assign assets.
  6. Select the app and grant the user full control to manage the app.

  7. Click on WhatsApp accounts, select the WhatsApp business account, and grant the user Full Control to manage the WhatsApp account. Then click Assign assets.

  8. Click Done.
  9. Click the Generate token button at the top-right corner of the page.

    10. The Generate token wizard appears.

  10. Select your app and click Next.

  11. Choose Never for the token expiration and click Next.

  12. Select the two WhatsApp permissions at the bottom of the list to assign them to the app, then click Generate Token.

  13. A permanent access token has been generated.

  14. Copy the token and save it, as you'll need it to activate the channel in the DRUID Portal. Then, click Done.

Remember, you can only share a token once. Each new system user requires a newly generated token.

Step 3: Activate the WhatsApp channel in DRUID Portal

  1. In the Druid ChatBot Portal got to your bot settings. Click the Channels tab, then click WhatsApp . The WhatsApp Channel Info section expands.
  2. In the WhatsApp Secret field, enter the secret of you app. To get the app secret:
    1. Log in Meta for Developers, select your app and go to the app basic settings.
    2. Click the Show button next to the App secret.

    3. Enter the password associated to your Facebook account and click Submit. The App secret is showed in the field.
    4. Copy the App secret.
  3. In the WhatsApp Number field, enter the phone number associated with your WhatApp business account or increase the WhatsApp business account, without the “+”. Go to WhatsApp Manager, and increase limits for your WhatsApp account by adding new phone numbers.

  4. Select Phone number validation if you have a Meta account connected to multiple bots to ensure the phone number uniqueness per bot; otherwise, WhatsApp will send messages to all the bots connected to the Meta account.
  5. In the WhatsApp Permanent Token field, enter the token you generated at Step 2.
  6. Generate the Webhook Verify Token by clicking the Generate button. This is a one-time password used to enable the webhook. Copy the token, as you'll need it to configure the WhatsApp webhook.
  7. In the WhatsApp API Host field, enter the following value: graph.facebook.com.
  8. In the WhatsApp API Version field, enter the API version your Meta app is using. Use the following format: vxx.x (e.g., v15.0).
    9. Hint:  To find out the API version of your app, go to Meta for Developers, log in, select your app and go to the app advanced settings. Check what the API version is.

  9. Copy the Druid Callback Url, you will need it to configure the WhatsApp webhook.

  10. Click the Publish button.
    11. Note:  After Druid confirms the activation, two fields are available in Druid: [[ChatUser]].ChannelId and [[ChatUser]].UserId. The value meta-whatsapp is stored in [[ChatUser]].ChannelId. For authentication purposes, the field [[ChatUser]].UserId stores an unique identifier of the WhatsApp user account.

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

    • [[ChatUser]].ChannelId = "meta-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.
  11. Click Save & Close to save the WhatsApp channel configuration.

Step 4: Enable Webhooks

In order to send messages and other events from your bot to WhatsApp, you must enable webhooks integration. To do so, follow these steps:

  1. In Meta for Developers, go to your app dashboard and on the menu click > WhatsApp > Configuration.The Configuration page appears.
  2. In the Webhook section, enter the Webhook Verify Token and the Druid Callback Url you copied from DRUID, then click the Verify and save button

    3. The Webhook fields appear on the page.

  3. Subscribe to message_template_status_update and messages

Once you finish the steps in the Enable webhooks section, the integration of the DRUID chat bot and WhatApp via Meta is complete.

Note:  The Meta app is in Development Mode until you publish it. The plugin and API functionality will only work for admins, developers and testers.

Submit the Meta app for review and after the review is successful, make the app public.

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

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

To associate multiple WhatsApp phone numbers to the same WhatsApp Meta application, go to WhatsApp Manager, and increase limits for your WhatsApp account by adding new phone numbers.

For more information, see Phone Number Limits.

Step 6. Talk to your bot

To open the chatbot in the WhatsApp channel, 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.

Note:  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 the 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