SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Getting Started with Twilio for WhatsApp

Overview

Twilio supports sending and receiving messages to and from WhatsApp users. The WhatsApp channel helps expand your reach and availability to your important contacts on any platform that is convenient for them. Best of all, WhatsApp messages are controlled by Twilio's existing Programmable Messaging API. Here's what you need to know to get started.

 

Environment

legacy Twilio Console

 

What You Need To Know

Twilio Sandbox for WhatsApp

The Twilio Sandbox for WhatsApp allows you to get started building and prototyping your applications immediately, without needing to register your WhatsApp Senders and Facebook Business Manager information first. The Sandbox provides a testing environment and shared Twilio test number to send  pre-approved template messages and receive messages from WhatsApp numbers that have joined your Sandbox.

To explore the Sandbox, visit the "Try It Out" section for WhatsApp in the Twilio Console.

 

Using WhatsApp in Production

If you are a new direct customer (you will be sending messages on behalf of your own brand and you are not working with an ISV) then you can get started straight away from the Console using our Self Sign-Up process. Find out more about Self Sign-Up here.

ISV customers should read the guide for the Tech Provider Program to understand the requirements and limitations associated with using the WhatsApp Business API with Twilio in production.

 

Messaging capabilities

WhatsApp messages over Twilio Programmable Messaging have the following capabilities and limitations:

Templates and Session messages: Outbound messages to WhatsApp users must be sent using one of the pre-approved templates. These are generally transactional messages (delivery alerts, appointment reminders, etc.) sent to users who have opted in to receive messages from you. To see the approved templates for the WhatsApp Sandbox, visit Console. You'll be able to submit your own templates for approval for use in production through the Console here.

All incoming messages, or outgoing replies to these messages within 24-hours, are considered Session messages, and don't need to follow a template. A messaging session starts when a user sends your application a message, and lasts for 24 hours from the most recently received message. For more info, please see "Templates and Sessions" in Rules and Best Practices for WhatsApp Messaging on Twilio.

 

Approved use cases: WhatsApp supports the following use cases:

  • Customer Care: initiated with an inbound message from an end user. When the first message is received from the user, it opens a conversation, in which the business can reply back with free-form (non-template) messages. The conversation will remain open for 24hrs from the last message received from the user.
  • Utility: Confirm or suspend an existing transaction, change or update a transaction, account, billing, or payment notification
  • Authentication: Send codes that allow your customers to securely access their accounts.
  • Marketing/Promotional: Send promotional offers, product announcements, and more to increase awareness and engagement.
     

Send a template message to a WhatsApp user

Sending messages with content templates is simple and prevents the mismatch errors that were common when using the WhatsApp Template system.

To send a template message using a Content Template, users only need to supply:

  • Recipient: The To parameter consisting of whatsapp: followed by the destination WhatsApp user number (using E.164 formatting).
  • Sender: The From parameter consisting of whatsapp: followed by the sending WhatsApp number (using E.164 formatting).
    • Until your Twilio number has been enabled, you may use the WhatsApp Sandbox number for testing and prototyping with WhatsApp.
  • ContentSid (this is the template sid that begins with HX)
  • ContentVariables (if applicable for the template)

Here’s an example cURL script:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
--data-urlencode "To=whatsapp:+13105555555" \
--data-urlencode "From=whatsapp:+12125551234" \
--data-urlencode "ContentSid=HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-u "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:your_auth_token"

 

Have more questions? Submit a request
We can’t wait to see what you build.
Powered by Zendesk