WhatsApp Business API | Integration with Microsoft Teams

Hi there!
Would you like to answer customers' WhatsApp messages in your Microsoft Teams?
In this tutorial, you will learn how to integrate WhatsApp Business API with Microsoft Teams. This integration will allow you to receive Whatsapp messages and respond to them in Teams using a custom Teams bot.

img_og_product_whatsapp_business_api_1x

You will need

Step One: Get your integration app ready

For your quick start with integrations, we’ve prepared a sample integration app. Let’s have a look at what the code does. You will notice that the code is in several directories:

  • server.js creates node.js server
  • config.js gets environment variables
  • errorHandler.js deals with possible errors
  • In the routes folder:
    • bot.js works as a router, a middleware function and ties logic together.

Follow these steps: 

1. Clone the api-sample repository and go to the wa-integrations/teamsbot directory.

2. Install dependencies (and the nodemon module if you don’t have it yet).

npm install
npm install nodemon

3. Afterward, you need to create a publicly accessible URL using ngrok. Launch ngrok with the local port 3000 using the command:

path/to/ngrok http 3000

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

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

Step Two: Subscribe your webhook in tyntec

Let tyntec Conversation API know where to deliver WhatsApp messages from customers. You’re going to subscribe your webhook via a PATCH request in Postman.

1. In our Postman collection, go to the Application Management folder, and open the patch Update default application

2. In the request body, change the callbackUrl for the MoMessage event to your /forwardTeams ngrok URL (for example: https://936cb7a8cce6.ngrok.io/forwardTeams).

The request body should look like this:

{
  "webhooks": [{
    "events": [
      "MoMessage"
    ],
    "callbackUrl": "https://<YOUR_SERVER>/forwardTeams"
  }]
}

3. Now hit Send and you should get the 204 status if everything was okay.

request2

Cool! Now tyntec knows where to deliver incoming WhatsApp messages.

Step Three: Get your Microsoft Teams ready

After subscribing your webhook, you are going to create a custom Teams bot which will handle receiving new WhatsApp messages and sending Teams messages. 

1. To create a new bot, you need to open App Studio. Click on the Teams Search bar and type in “App Studio”.

app_st

2. First, you need to create a new app, in which you can create a Teams bot. In the given Chat, navigate to Manifest editor. Click on Create a new app.

ms_teams2

3. On the App details page, provide Microsoft with information about your Teams bot.

All the fields are mandatory except Partner information and Branding.

app_details3

4. On the left side of your screen, under the 2 Capabilities section, click on Bots. On the following page, click on Set up.

details

5. A pop-up with information on your Teams bot appears. Fill the name of your bot and set Scope to Personal. Then press Create bot.

setup_bot

Note: Personal scope means that it is 1-1 bot. The sample app might be running a Group or Team bot but Personal is the most suitable option for testing and development.

6. After your bot is created, copy the ID of your bot. You will need it for the final configuration.

tets4

7. To control your bot programmatically, you also need an app password. Click on Generate new password and save it securely. After saving it, click on OK.

bots

8. You can now control your Teams bot using code. Now you need to add a Messaging endpoint, which is a Callback URL. Click into it and type https://<YOUR_SERVER>/forwardWhatsApp.

After typing, be sure to press Enter. Wait until a small green indicator notifies you about successful registration.

9. After registering, the endpoint of your Teams bot is ready to be installed. On the left side, scroll to section 3 Finish and select Test and Distribute. By clicking on Install, you add your custom Teams bot to your Teams.

test_distribute

Note: Some users may experience issues when installing a custom Teams bot. You can work around these issues by downloading your bot and then importing it. After a successful import, you should be able to install it.

You’re all set in Teams!

Step Four: Configure and run your app

After setting up your Teams bot, the last thing you need to do is to configure your sample app. 

1. Copy the .env-example file to .env and set environment variables in .env:

  • TYNTEC_WABA_NUMBER – your WABA number in the international format without the leading 00
  • TYNTEC_API_KEY – your API key from tyntec to authenticate calls to Conversations API
  • PORT – optional server port (defaults to 3000)
  • MICROSOFT_BOT_ID – your Teams bot ID 
  • MICROSOFT_BOT_PASSWORD – password to your Teams bot

2. Start the app in another terminal: 

nodemon server.js

Everything is now up and running. Good job!

Step Five: Try it out!

It's Testing Time!

1. Go to the Chat with your custom Teams bot and initiate conversation.

Your first message just flags you as a free agent. After sending any text message, the custom Teams bot informs you that you will now receive messages from WhatsApp.

test1

2. Grab your phone and send some warm WhatsApp message to your WhatsApp Business Account number. 

3. Look back to the Chat with your custom Teams bot.

You receive the WhatsApp message and try replying to the message.

4. Afterward, go back to your testing WhatsApp.

You should see your reply. Voilà!

Congratulations on your integration!

More?

You may want to use Microsoft Teams as an omnichannel for all your communication. To enhance Teams conversation capabilities, you should consider:

  • Adding support for multiple conversations at once. To support multiple conversations you would need to change the scope of your custom Teams bot. Alternatively, you could store information about your customers in the messages as a prefix.
  • Adding support for agent handovers. If you want to use Teams as an omnichannel dashboard, supporting agent handovers is crucial. You would need to change the scope of your custom Teams bot to support group chats.
  • Flagging yourself unavailable. The current version informs users about unavailable Agents (if no Agent has messaged the custom Teams bot). One of the possible solutions is to add custom Command to the custom Teams bot which would change your status to Unavailable. 
  • Using tyntec Conversations API to support Viber and SMS messages as well. You can implement these two channels together with adding support for multiple conversations.