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:
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!
You can test your application in a developer environment by connecting to Twilio Sandbox for WhatsApp.
Navigate to the Messaging > Try it out > Send a WhatsApp section in the Twilio Console. 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".
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.
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.
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
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!
Let’s start a Conversation by sending a WhatsApp message to the Twilio sandbox phone number.
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.
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.
Congratulations! 🎉 You have learned how to connect the Twilio's Sandbox for WhatsApp with Conversations. As a following step, you can: