How to set up a WhatsApp integration

WhatsApp is one of the most popular messaging platforms around. In this guide, you’ll learn how to add the WhatsApp integration.


Before you begin

This integration requires a Twilio account. Twilio lets you connect with customers everywhere they want to interact with you, including text messages, emails, phone calls, video, and, of course, WhatsApp.

Adding the Twilio integration

Retrieve Twilio credentials

First, you’ll need to gather your Twilio account SID and authentication token.


If you’re just testing the integration out and don’t want to send real messages yet, Twilio provides test credentials you can use. See the Test Credentials section below for details.

Live credentials

Login to your Twilio console. In the Project Info box you’ll see your Account SID. Make a note of this value as you’ll be using it in the following step.


Test credentials


If you’re using your Twilio live credentials, you can skip ahead to Activate the WhatsApp sandbox.

If you’re not ready to use your live Twilio credentials, you can use test credentials instead. Here’s how.

  1. From the Account menu (top right), select API keys & tokens. In the Test Credentials box, make a note of the Test Account SID and Test Auth Token values.

Create the API key

Navigate to the API keys & tokens page. Click the Create API key button. Make sure the type is set to Standard.


Make a note of the API secret and SID values.

Activate the WhatsApp sandbox

In your Twilio console, click the project name in the top left bar. From the products menu on the left, choose Messaging. Then choose Settings → WhatsApp sandbox settings.

Near the bottom there will be a button to activate the sandbox. Click it and walk through the setup instructions. Once complete, you’ll have a number you can send and receive WhatsApp messages with. You should see your phone number in the Sandbox Participants section, as well.

Add secrets to the vault

The vault is used to store secret information that shouldn’t be committed to version control. Let’s store the Twilio credentials there.

  1. In your app’s root folder, open vault.yaml and copy this code into it:
twilio.account_sid: xxx
twilio.api_key_sid: xxx
twilio.api_key_secret: xxx
whatsapp.phone_number: xxx


Remember not to store the actual values in your vault.yaml file. Just leave them set to xxx.

  1. Open vault.secret.yaml and copy this code into it:
twilio.account_sid: ACCOUNT_SID
twilio.api_key_sid: API_KEY_SID
twilio.api_key_secret: API_KEY_SECRET
whatsapp.phone_number: "whatsapp:PHONE_NUMBER"

Replace the values with your actual Twilio credentials. The phone number will be the one you created when activating the WhatsApp Sandbox in Twilio, or another Twilio-approved WhatsApp number you’ve purchased.


Depending on the format of the phone number, you may need to wrap it in quotes to ensure the app interprets it as a string, instead of an integer.

  1. Save these files and upload the new vault secrets using this command in your terminal:
meya vault upload --file vault.secret.yaml

Create the integration

Now that you’ve stored your credentials, you can create the integration using references to the vault.

In your app’s integration folder, create a new file called whatsapp.yaml and copy this code into it:

type: meya.whatsapp.integration
account_sid: (@ vault.twilio.account_sid )
api_key_sid: (@ vault.twilio.api_key_sid )
api_key_secret: (@ vault.twilio.api_key_secret )
phone_number: (@ vault.whatsapp.phone_number )
markdown: true

Save the file.

Add your webhook to the WhatsApp Sandbox

To receive messages from WhatsApp and pass them from Twilio to your app, you’ll need to add your Meya webhook to the Twilio WhatsApp Sandbox.

  1. Run this command in your terminal:
meya webhooks

Look for an entry called integration.whatsapp. The webhook will look like this:

  1. Copy the webhook and go back to your Twilio WhatsApp Sandbox Settings. Paste the webhook into the When a message comes in and Status callback URL boxes. Make sure both to select HTTP POST in the drop-down menus next to these boxes.

Click the Save button.

Connecting to your WhatsApp number

Right above the Sandbox Participants box, you’ll see a note telling you how to begin interacting with your WhatsApp number. There will be a phrase with a format like this: join SOME-PHRASE. Make a note of it since you’ll need it later.

Use WhatsApp as a messaging channel

Create a flow

Let’s create a basic flow to see if we can send WhatsApp messages to and from our app.

In your app’s flow folder, create a new file called hi.yaml. Copy this code into the file:

  - keyword: hi

  - say: Hello! Great to meet you.

Save the file and upload your work:

meya format
meya push

Try it out

Open WhatsApp. If you haven’t already done so, send the special joining phrase to your WhatsApp number. The phrase has the format join SOME-PHRASE. You’ll get a welcome message in response, which confirms your number has been added as a sandbox participant.

To trigger the flow, type hi.



Great! You’ve set up the WhatsApp integration and confirmed that users can send and receive messages from your app.


If anything is misconfigured in your Twilio account, Twilio’s API will return an error message explaining what went wrong. You can find these responses in your app’s Log page using this GridQL query:

url:*twilio* type:meya.http.entry.response

For detail on Twilio errors and how to fix them, check out their documentation.