Trying Out WhatsApp with Conversations

In this tutorial, we’ll explore how you can use Twilio’s Conversations with Twilio’s Sandbox for WhatsApp. Twilio controls a dedicated WhatsApp phone number that you can use to test WhatsApp with Conversations.

You will need a few things before you start this tutorial:

• A Twilio Account - sign up here if you don't have one yet.
• The Twilio CLI.

Note: We’re using the Twilio CLI to make API requests to Twilio’s Conversations service, but you can choose another method such as a helper library.

Let’s get started!

Step 1: Opt-in to the Twilio Sandbox for WhatsApp

You can test your application in a developer environment by connecting to Twilio Sandbox for WhatsApp.

Navigate to the Conversations > Try it out section in the Twilio Console. Choose a use case - then, send the "join <your Sandbox keyword>" WhatsApp message from your device to the Twilio Sandbox for WhatsApp phone number to connect to your sandbox.

Once you’ve joined Twilio WhatsApp Sandbox, you’ll receive a confirmation message. To disconnect from the sandbox, you can reply to the message from WhatsApp with the word "stop".

Optional: Remove the Inbound URL in the WhatsApp sandbox settings in the Twilio Console

In this tutorial, we won’t need to set a webhook URL for inbound messaging. Let’s remove the existing testing webhook URL configured in the WhatsApp Sandbox’s settings section. Not doing so would result in an automatic reply requesting to update the configuration for your WhatsApp Sandbox’s Inbound URL when you send your first message.

To update the WhatsApp Sandbox inbound URL, go to the Messaging > Settings > WhatsApp sandbox settings section in the Twilio Console and remove the webhook URL. Click Save.

Step 2: Create a Conversation

Now that you have your Twilio Sandbox for WhatsApp configured, it’s time to create your first Conversation!

Let’s make a Conversation using the Twilio CLI (but remember that you can choose another tool for making the API requests):

# Install the twilio-cli from https://twil.io/cli

twilio api:conversations:v1:conversations:create \
    --friendly-name "sandbox-test"

Copy down the Conversation SID - it starts with CHXXXXXXX. You’ll use this value in the next steps.

Step 3: Add a WhatsApp Participant to the Conversation

You’ve created a Conversation, which you can think of as a virtual space that users can join using a channel of their choice.

Next, you’ll add yourself as a WhatsApp Participant. The following code sample does this for you. You’ll need to replace the following information:

• CHXXXXXXXXXXX - the Conversation SID.
• YOUR_WHATSAPP_NUMBER - your own mobile phone number in E.164 format.
• TWI_SANDBOX_WA_NUMBER - the Twilio Sandbox WhatsApp phone number in E.164 format.

# Install the twilio-cli from https://twil.io/cli

twilio api:conversations:v1:conversations:participants:create \
    --conversation-sid CHXXXXXXX \
    --messaging-binding.address whatsapp:YOUR_WHATSAPP_NUMBER \
    --messaging-binding.proxy-address whatsapp:TWI_SANDBOX_WA_NUMBER

Step 4: Add a chat Participant to the Conversation

For this step, you’ll add a chat Participant to the Conversation (remember that you can also add an SMS Participant).

The following code sample does this for you. You’ll need to replace the following information:

• CHXXXXXXXXXX - the Conversation SID.
• <Chat_User_Identity> - the identity of your chat user. In this tutorial, we'll use "chat-user".

# Install the twilio-cli from https://twil.io/cli

twilio api:conversations:v1:conversations:participants:create \
    --conversation-sid CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
    --identity "<Chat_User_Identity>"

New Conversation? Check! Two Participants? Check!

Great! Now, it’s time to start talking!

Step 5: Send a Message from WhatsApp to the Sandbox number

Let’s start a Conversation by sending a WhatsApp message to the Twilio sandbox phone number.

Step 6: Reply to the message

Let’s reply to the previous message from the REST API. Remember that you can do it from the SDK or SMS (if that’s how you added the second Participant).

Make sure to replace CHXXXXXXX for your Conversation SID, the <Chat_User_Identity> with "chat-user" and add the content of the message that you’d like to send. For example, we'll use "Hello from the other side 👋🏼".

The following code sample does this for you:

# Install the twilio-cli from https://twil.io/cli

twilio api:conversations:v1:conversations:messages:create \
    --conversation-sid CHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
    --author "<Chat_User_Identity>" \
    --body "Hello from the other side 👋🏼"

Well done! You've successfully connected your Twilio’s WhatsApp Sandbox Number with Conversations.

Step 7: Twilio Conversations Logs

To check if the WhatsApp message arrived in the Conversation, navigate to Monitor > Logs > Errors > Conversations and click the Conversation you created previously. You’ll see on the top of the page the name of the Conversation you created. Click the Messages tab to see, for example, the WhatsApp phone number and chat identity that was used in the Conversation and the content of the message.

What's Next?

Congratulations! 🎉 You have learned how to connect the Twilio's Sandbox for WhatsApp with Conversations. As a following step, you can:

• Learn more about how to Use WhatsApp with Conversations
• Check out our Conversations Quickstart