Skip to content

voiceflow/example-integration-whatsapp

Repository files navigation

Example code for Voiceflow and WhatsApp integration

How to use WhatsApp Cloud API with Voiceflow Dialog Manager API


Before you begin

This guide is intended for people building an integration for their own organizations. If you are building an integration that will be used by another business, see Meta's Get Started for Solution Partners doc or their Get Started for Tech Providers doc.

Create an app on Facebook Developers portal

Follow the Get started guide here to create your app and get your WhatsApp token. https://developers.facebook.com/docs/whatsapp/cloud-api/get-started

Get Started

The app

Once registered as a dev, go to https://developers.facebook.com/apps/

Create a new app by clicking on create a new app

Select "Other" for the use case business app and click Next

Select "Business" for app type business app and click Next

Fill the needed info for the app creation app info and click Create app

On the next page, scroll down to the WhatsApp integration whatsapp integration and click on Set up

Create a Business account (or select an existing one) business account

Go to https://business.facebook.com/home/accounts to add a system user. Select your Business account and click on the gear (Settings) business account

In Users section, select System users and then click on Add business account

Create a new system user with the Admin role business account

Once created, click on the Generate new token button. business account

Select your app, set the token expiration to Never, select the permissions as bellow and click on the Generate token button. business account

Save your token for later and click OK when it's done. business account


Now go to the Accounts section > WhatsApp Accounts and click on Add people business account

Select the newly created system account, toggle Full control and click on Assign business account
business account valid

Go back to your Dashboard (https://developers.facebook.com/apps/) and link an existing number or create a new one add number

You can add your phone number by clicking on Manage phone number list

Now that you are ready to do a test, simply click on the Send message button. send message

You should get something like this in your WhatsApp app test message

Webhook

Using Replit

Fork the following Replit project: https://replit.com/@niko-voiceflow/example-integration-whatsapp?v=1

Open the Secret tool, click on Edit as JSON and copy/paste the following JSON code
test message

Optional: To support audio messages you will need to use an API key available on PicoVoice Dev console https://console.picovoice.ai/

{
  "PICOVOICE_API_KEY": "",
  "WHATSAPP_VERSION": "v17.0",
  "WHATSAPP_TOKEN": "",
  "VERIFY_TOKEN": "voiceflow",
  "VF_API_KEY": "",
  "VF_PROJECT_ID": "",
  "VF_VERSION_ID": "development",
  "VF_DM_URL": "https://general-runtime.voiceflow.com",
  "VF_TRANSCRIPT_ICON": "https://s3.amazonaws.com/com.voiceflow.studio/share/200x200/200x200.png",
  "PORT": 3000
}

Update the keys accordingly with the values you got from the previous steps.

You can find your Dialog API key (VF_API_KEY) in the integration tab in Creator and the project ID (VF_PROJECT_ID) in the project settings (this is needed if you want to save transcripts).

For the VF_VERSION_ID, you can use 'development', 'production' or a specific version ID (from the project settings).

Once done, click on Run and you should see something like this: run

From the webview tab, you want to copy the URL.

WhatsApp Webhook

Back on our Getting Started Facebook Developer page, click on the Configure webhooks link step 3

On this new page, click on Edit
edit webhook

This is where you will need to set your webhook's callback URL and your Verify token
edit webhook 2

Do not forget to add /webhook at the end of the URL and the verify token you set in the Replit secrets.
When ready, click on Verify and Save. webhook

On your Replit console, you should see this message: WEBHOOK_VERIFIED

Last step, we want to choose what to receive, and to do so, we need to subscribe to the message event.

Click on Manage and, on the new window, subscribe to messages manage

You should have a config similar to this one

sub-messages

Using ngrok (local)

Prepare your dev environement

Clone this repo

git clone https://github.com/voiceflow/example-integration-whatsapp.git

In the example-integration-whatsapp, do a:

npm i

Install ngrok, more details here: https://ngrok.com/download

Before going further, let's start populating our .env file with our token. In the root of the app directory, rename the .env.example file to .env
We are going to populate this file with the needed info for the WhatsApp webhook as well as the Voiceflow project.

Optional: To support audio messages you will need to use an API key available on PicoVoice Dev console https://console.picovoice.ai/

{
  "PICOVOICE_API_KEY": "",
  "WHATSAPP_VERSION": "v17.0",
  "WHATSAPP_TOKEN": "",
  "VERIFY_TOKEN": "voiceflow",
  "VF_API_KEY": "",
  "VF_PROJECT_ID": "",
  "VF_VERSION_ID": "development",
  "VF_DM_URL": "https://general-runtime.voiceflow.com",
  "VF_TRANSCRIPT_ICON": "https://s3.amazonaws.com/com.voiceflow.studio/share/200x200/200x200.png",
  "PORT": 3000
}

For now, you can paste the token for the WHATSAPP_TOKEN variable, you can use anything for the VERIFY_TOKEN or leave it to 'voiceflow'.

Regarding the port, you can put the value you want, by default the app will use 3000

You can find your Dialog API key (VF_API_KEY) in the integration tab in Creator and the project ID (VF_PROJECT_ID) in the project settings (this is needed if you want to save transcripts).

For the VF_VERSION_ID, you can use 'development', 'production' or a specific version ID (from the project settings).

WhatsApp Webhook

Back on our Getting Started Facebook Developer page, click on the Configure Webhook link
step 3

On this new page, click on Edit
edit webhook

This is where you will need to set your webhook's callback URL and your Verify token
edit webhook 2

For the Verify token, put what you've set in your .env file (voiceflow by default)

For the Callback URL to be accessible, we will need to start the app.

From the root of the directory, start the app with

npm start

And if everything work as expected, you should have something similar to this

app start

We are listening, let's use ngrok to open this to the world.

In a new terminal, type

ngrok http 3000

Replace 3000 with the PORT number you choose to use.

ngrok console
Here, the URL you want to copy is the secure one (starting with https) Almost there, go back to your Config page, paste this URL and add the /webhook path to it.
webhook url

And click on Verify and save If everything is fine, the previous window should close and your webhook ready.
webhook setup

On your terminal, you should see this message: WEBHOOK_VERIFIED

Last step, we want to choose what to receive, and to do so, we need to subscribe to the message event.

Click on Manage and, on the new window, subscribe to messages manage

You should have a config similar to this one

sub-messages

Testing

Congratulations, you are ready to test your Voiceflow project using WhatsApp!
Use the WhatsApp app on your phone to send a message to the number you got from the Quickstart > API Setup page.
wa-number

demo

publish-button

Documentation

Cloud API: https://developers.facebook.com/docs/whatsapp/cloud-api
Voiceflow Dialog Manager API: https://docs.voiceflow.com/docs/deploy-whatsapp
Project Versioning in Voiceflow: https://docs.voiceflow.com/reference/project-ids-and-versions