How to use WhatsApp Cloud API with Voiceflow Dialog Manager API
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.
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
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
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.
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
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).
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
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.
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
![@renovate[bot]](https://avatars.githubusercontent.com/in/2740?s=64&v=4){kind=small}