Using WhatsApp with Conversations

WhatsApp is increasingly the world's #1 conversational messaging platform as well as an absolutely critical engagement tool across South America, Middle East, Africa and many parts of Europe and Asia. Twilio Conversations supports WhatsApp out of the box and can help you address a number of patterns:

Delivery Coordination: Let your drivers reach out to the customer to make sure the last 100 yards of each delivery are successful.
Clienteling: Allow your employees to have long-term relationships (e.g. personal shoppers, wealth managers, or real estate agents) with your customers without using their personal devices.
Masked Communication: Facilitate communication between your employees and your customers without sharing private numbers.

This guide will show you how to set up a few common patterns that pair WhatsApp with other channels.

Prerequisites

(information)

Info

Please note that WhatsApp onboarding generally takes 1-2 weeks. WhatsApp has a thorough vetting process that requires business verification in the Meta Business Manager in order to protect the WhatsApp ecosystem.

We advise planning accordingly when setting up your WhatsApp Sender for Twilio. For more information, please read our guide to connecting your WhatsApp Business Profile with your Twilio number.

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.

Get your WhatsApp templates approved

(information)

Info

The last section of the tutorial uses templates to initiate contact between two separate WhatsApp participants. If you follow the steps chronologically, you will still be able to complete the tutorial because you will have opted into the WhatsApp's 24-hour window. However, the screenshots will looks lightly different from what you see in the WhatsApp interface.

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!

Cross-Channel Masking: Connecting WhatsApp to SMS

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.

Step 1. Create a Conversation

Create a Conversation

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

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_10// Download the helper library from https://www.twilio.com/docs/node/install
_10// Find your Account SID and Auth Token at twilio.com/console
_10// and set the environment variables. See http://twil.io/secure
_10const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10const authToken = process.env.TWILIO_AUTH_TOKEN;
_10const client = require('twilio')(accountSid, authToken);
_10
_10client.conversations.v1.conversations
_10                       .create({friendlyName: 'SMS-to-WhatsApp Example'})
_10                       .then(conversation => console.log(conversation.sid));

Output


_25{
_25  "sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "chat_service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "friendly_name": "SMS-to-WhatsApp Example",
_25  "unique_name": "unique_name",
_25  "attributes": {
_25    "topic": "feedback"
_25  },
_25  "date_created": "2015-12-16T22:18:37Z",
_25  "date_updated": "2015-12-16T22:18:38Z",
_25  "state": "inactive",
_25  "timers": {
_25    "date_inactive": "2015-12-16T22:19:38Z",
_25    "date_closed": "2015-12-16T22:28:38Z"
_25  },
_25  "bindings": {},
_25  "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_25  "links": {
_25    "participants": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_25    "messages": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages",
_25    "webhooks": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Webhooks"
_25  }
_25}

Step 2: Create the WhatsApp Participant

Create the WhatsApp Participant

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

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_14// Download the helper library from https://www.twilio.com/docs/node/install
_14// Find your Account SID and Auth Token at twilio.com/console
_14// and set the environment variables. See http://twil.io/secure
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = require('twilio')(accountSid, authToken);
_14
_14client.conversations.v1.conversations('CHxxxx')
_14      .participants
_14      .create({
_14         'messagingBinding.address': 'whatsapp:YOUR_WHATSAPP_NUMBER',
_14         'messagingBinding.proxyAddress': 'whatsapp:TWI_WA_NUMBER'
_14       })
_14      .then(participant => console.log(participant.sid));

Output


_20{
_20  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "identity": null,
_20  "attributes": {
_20    "role": "driver"
_20  },
_20  "messaging_binding": {
_20    "type": "sms",
_20    "address": "+15558675310",
_20    "proxy_address": "+15017122661"
_20  },
_20  "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "date_created": "2015-12-16T22:18:37Z",
_20  "date_updated": "2015-12-16T22:18:38Z",
_20  "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "last_read_message_index": null,
_20  "last_read_timestamp": null
_20}

Step 3: Create the SMS Participant

Create the SMS Participant

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

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_14// Download the helper library from https://www.twilio.com/docs/node/install
_14// Find your Account SID and Auth Token at twilio.com/console
_14// and set the environment variables. See http://twil.io/secure
_14const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14const authToken = process.env.TWILIO_AUTH_TOKEN;
_14const client = require('twilio')(accountSid, authToken);
_14
_14client.conversations.v1.conversations('CHxxxx')
_14                       .participants
_14                       .create({
_14                          'messagingBinding.address': 'YOUR_SMS_NUMBER',
_14                          'messagingBinding.proxyAddress': 'TWI_SMS_NUMBER'
_14                        })
_14                       .then(participant => console.log(participant.sid));

Output


_20{
_20  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "conversation_sid": "CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "sid": "MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "identity": null,
_20  "attributes": {
_20    "role": "driver"
_20  },
_20  "messaging_binding": {
_20    "type": "sms",
_20    "address": "+15558675310",
_20    "proxy_address": "+15017122661"
_20  },
_20  "role_sid": "RLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "date_created": "2015-12-16T22:18:37Z",
_20  "date_updated": "2015-12-16T22:18:38Z",
_20  "url": "https://conversations.twilio.com/v1/Conversations/CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants/MBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20  "last_read_message_index": null,
_20  "last_read_timestamp": null
_20}

Step 4: Send a message from WhatsApp

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.

3.66.1 or higher.