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

The app

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

Create a new app by clicking on

Select "Other" for the use case and click Next

Select "Business" for app type and click Next

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

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

Create a Business account (or select an existing one)

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

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

Create a new system user with the Admin role

Once created, click on the Generate new token button.

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

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

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

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

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

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.

You should get something like this in your WhatsApp app

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

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:

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

On this new page, click on Edit

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

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.

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

You should have a config similar to this one

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

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

On this new page, click on Edit

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

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

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.

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.

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

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

You should have a config similar to this one

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.