Using WhatsApp with Conversations

WhatsApp is a highly-regulated channel, requiring documentation and approval from Meta to get your business started. Specifically, you will need to secure an approved WhatsApp Business Profile, which gives you a Twilio WhatsApp Number to represent your business.

Depending on your use-case, you may need to secure some approved WhatsApp templates. This is specifically required if you want to send a message to a new user on WhatsApp, or send a message more than 24 hours after the last response.

Note: If your use case can function such that you always receive WhatsApp messages first from your customers, you can skip the template registration step.

Now, you're ready to go!

SMS is the easiest channel to connect to WhatsApp in a Twilio Conversation. To do this we'll use:

• A Twilio SMS-capable phone number (hereafter "TWI-SMS-NUMBER")
• Your Twilio WhatsApp number (hereafter "TWI-WA-NUMBER")
• The Twilio CLI

We recommend the Twilio CLI for experimenting, but these guides will work in any language in Twilio. Pick your favorite on the right and follow along.

Let's get down to it; our SMS-to-WhatsApp conversation will take four steps to set up.

The Conversation will contain two participants, one on SMS and the other on WhatsApp.

Use your own WhatsApp phone number and the business profile you created.

Use your phone number and a Twilio SMS Number from your account.

Because you've set up this conversation to proxy with SMS, you'll see the messages flowing back and forth automatically between your two channels.

Note: The WhatsApp user kicks off this conversation by sending the first message. By starting from an inbound WhatsApp message, we've avoided any need to use WhatsApp Templates to start the Conversation. These messages and media will flow just fine for the next 24 hours.

Expand image

When you connect two WhatsApp participants, you'll have to solve two business problems:

1. Who is speaking with whom?
   This is probably the bread-and-butter of your business idea: if you're a two-sided marketplace, you're probably connecting a buyer and a seller (or a passenger and a rider). The buyer is the most critical personality: the brand they see in WhatsApp is important and must establish enough trust to proceed with the conversation. When you create your WhatsApp Business Profile , keep that buyer personality in mind first.
2. How will you get opt-in from both participants?
   Unsolicited outbound messages to WhatsApp are highly restricted. Until your customer replies, you can only send messages conforming to approved templates. In this scenario, both sides are on WhatsApp, so we will need to use one of those templates to get the conversation moving.

We'll start by setting up the Conversation and later show how to use templates to improve the customer experience.

We'll need the following to set up our WhatsApp-to-WhatsApp Conversation:

1. A Twilio WhatsApp number; we'll call this "TWI_WA_NUMBER." You could use more than one, but it's not necessary.
2. Two consumer WhatsApp accounts. Choose yourself and a friend who won't mind. These are typically your personal device numbers.
3. The Twilio CLI .

With that, connecting two WhatsApp participants in a Conversation will take five steps:

The Conversation will map your two participants to each other, one on SMS and the other on WhatsApp.

Run this code twice, replacing YOUR_WHATSAPP_NUMBER with your phone number the first time and your friend's the second time

From your phone, send the first message in WhatsApp. Send the message to your TWI_WA_NUMBER (not directly to your friend's number.)

Have your good-natured friend send a message to your TWI_WA_NUMBER (not directly to your phone number).

Expand image

Congratulations, it's working!

… Mostly. You may notice that after steps four and five, you have two different conversations ongoing. After this awkward introduction, everything proceeds as expected, but that's not the professional experience we want.

In this scenario, both WhatsApp-based parties must reply before the Twilio can send outbound messages to both parties. Receiving an incoming message from both Conversation participants kicks off the "24-hour session" in which Twilio can send outbound free-form WhatsApp messages.

Let's carry the example above a little further, and use approved WhatsApp Template Messages to make it happen. We're going to pick two template messages that we've already gotten approved:

• A templated message that our food courier will understand
• A templated message that will invite the customer to opt into the contact.

We'll send these messages one after another, waiting for a response from the first before sending the second.

Using templates to smooth out our customer experience, let's follow two more steps:

Use the REST API to send the first message as though it were authored by the courier. Note the 'author' parameter.

The following is what the customer will see after you send the first templated message as the courier/rider:

Expand image

You'll notice when you do this that the customer receives a message, but the courier does not. We're using the rules of WhatsApp's 24-hour opt-in window in our favor: securing one participant's opt-in (from the customer) before we reach out to the other (the courier).

In the picture above, you notice that we included an automated reply: "Great! Just a moment…" This picture is a step ahead. To actually execute this — and at the same time to opt-in our courier — we're going to need a Twilio function and a Conversations webhook.

Let's start with the former.

First, navigate to the Twilio Functions section of the Console and click on "Configure." Confirm that the version listed for the twilio NPM module is up-to-date, such as 3.66.1 or higher.

Expand image

Next, create a Twilio Function in the console with the following code, which will set us up to capture the onMessageAdded event.

To power this, we'll add a Conversation Scoped webhook that we can remove later.

Replace the configuration.url field with the address of your new Twilio Function.

Now let's start again by sending the initial opt-in message to test the whole flow.

Expand image

With all this setup, we've created the ideal experience for two-sided WhatsApp Conversations. Notice how system messaging manages expectations while we're still opting-in the second party. And after the initial setup, notice that we're not forwarding messages one-by-one among the parties: all of that happens automatically via Twilio Conversations platform. It only ends if/when you DELETE the conversation later on.

Note: Our templates fit neatly in WhatsApp's guidelines: they are not promotional, but rather they facilitate an active transaction. By following these patterns, your business could benefit from the same pattern.

Ready to learn more about Conversations and WhatsApp? Learn more with the following resources:

• Send WhatsApp Notification Messages with Templates
• Connecting your Twilio Number with your WhatsApp Business Profile
• The Conversations API Reference
• The Conversations Scoped Webhook Resource