WhatsApp Business API | Integration for the Microsoft Bot Framework

logo_microsoft_bot_framework_ct2x
Hi there!

Do you want to have your Microsoft bot more accessible? What about adding WhatsApp as one of the channel options? If that sounds good, look no further.

In this tutorial, you will learn how to integrate a simple Echo bot built from the Microsoft Bot Framework with the WhatsApp channel in the tyntec Conversations API. This integration allows your bot to receive WhatsApp messages and reply to them with ease.

You will need

Step One: Build an Echo bot

Let’s create artificial intelligence!

1. Use Yeoman to generate an Echo bot.

$ yo botbuilder
Welcome to the Microsoft Bot Builder generator v4.14.0.
 
Detailed documentation can be found at https://aka.ms/botbuilder-generator
 
? What's the name of your bot? my-chat-bot
? What will your bot do? Demonstrate an integration of the tyntec Conversations API and the Microsoft Bot Framework
? What programming language do you want to use? TypeScript
? Which template would you like to start with? Echo Bot
? Looking good.  Shall I go ahead and create your new bot? Y

2. Change your current working directory to the bot folder. It has the same name as your bot.

$ cd my-chat-bot

Step Two: Install the WhatsApp adapter

Connect the bot to the tyntec Conversations API. You are going to replace the original BotFrameworkAdapter with the TyntecWhatsAppAdapter.

1. Install the WhatsApp adapter.

$ npm install botbuilder-adapter-tyntec-whatsapp

2. Replace the initialization of a BotFrameworkAdapter object with a TyntecWhatsAppAdapter object in the src/index.ts file.

-const adapter = new BotFrameworkAdapter({
-    appId: process.env.MicrosoftAppId,
-    appPassword: process.env.MicrosoftAppPassword 
-});
======================================
+import axios from 'axios';
+import { TyntecWhatsAppAdapter } from 'botbuilder-adapter-tyntec-whatsapp';
+
+const axiosInstance = axios.create();
+
+const adapter = new TyntecWhatsAppAdapter({
+    axiosInstance,
+    tyntecApikey: process.env.TyntecApikey
+});

3. Import Activity in the src/bot.ts file.

-import { ActivityHandler, MessageFactory } from 'botbuilder';
======================================
+import { Activity, ActivityHandler, MessageFactory } from 'botbuilder';

4. Replace the call of the MessageFactory.text method with a manual initialization of an Activity object in the src/bot.ts file.

this.onMessage(async (context, next) => {
             const replyText = `Echo: ${ context.activity.text }`;
-            await context.sendActivity(MessageFactory.text(replyText, replyText));
======================================
+            const activity = {
+                type: 'message',
+                channelId: 'whatsapp',
+                from: { id: process.env.Waba },
+                conversation: { id: context.activity.from.id },
+                channelData: { contentType: "text" },
+                text: replyText
+            };
+            await context.sendActivity(activity as Activity);
             await next();
         });

S​​tep Three: Configure and run the bot

Now, you will configure and run the bot.

1. Add the following environment variables to the .env file:

  • TyntecApikey - your tyntec API key
  • Waba - your WABA phone number

2. Start the bot.

$ npm start

3. Create a publicly accessible URL using ngrok.

$ path/to/ngrok http 3978

4. Copy the displayed public URL (such as https://843fc8776770.ngrok.io).

Note: This setup is suitable only for development. For production use, you have to deploy your app properly!

Step Four: Register the bot’s webhook

Let the tyntec Conversations API know where to deliver WhatsApp messages from customers or your users. You’re going to subscribe to the bot’s webhook via an API call in Postman.
 

1. From the api-collection/conversations/v3 directory, import the Conversations V3.0.postman_collection.json into Postman.

2. Authorize Postman with your tyntec API key and your WABA phone number. Right-click the collection and select Edit. Then go to Variables and set the apiKey variable to your tyntec API key. Also set the wabaNumber variable to your WABA phone number.

3. Let's set up the webhook! Open the WhatsApp folder. Inside, open the Configurations folder and select the Configure the callback for a specific number request and change the inboundMessageUrl in the body to the public URL of your /api/messages endpoint (for example, https://843fc8776770.ngrok.io/callback/message). This request will subscribe to your URL to incoming message events.

Set your Webhook in Conversations API

4. Hit the Send button. You should receive a 2xx status in the response if everything is okay.

Cool! Now Conversations API knows where to deliver WhatsApp messages from your customers.

Step Five: Try it out!

Now you can test all the functionalities.

1. Grab your phone and send some warm message to your WhatsApp Business Account number. In a few moments, you will see a reply from your own Echo bot.

A message from your first bot. Cool, isn't it?

Voila! Your Microsoft bot now can interact with your WhatsApp contacts!

More?

For example, you may want to reply with a snappy meme using an image message or with a funny cat video using a video message. The adapter supports audio, document, image, sticker, template, text and video messages.

To test a more sophisticated bot, you can generate the Core Bot using the Yeoman generator and connect it to the WhatsApp adapter.

For production use, you can deploy your bot following the deployment tutorial.

In order to protect the bot’s /api/messages endpoint against unauthorized messages, you can register the webhook with a custom header containing a bearer token. Then, you can override the adapter’s parseTyntecWhatsAppMessageEvent method and check the request headers before parsing the request body. See the API Reference for more information: https://github.com/tyntec/botbuilder-adapter-tyntec-whatsapp/tree/master/docs