Getting Started with Twilio for WhatsApp (Beta)

Twilio now 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 SMS API. Here's what you need to know to get started.

Notice: The WhatsApp Channel is currently in beta, and has not yet been finalized. For more information on Support limitations for beta products, please see our article Twilio Beta Product Support.

Twilio Sandbox for WhatsApp

In order to use WhatsApp in production, you must first submit your use case for review by WhatsApp. To get started building and prototyping your applications immediately, Twilio has created a sandbox environment for testing. The Sandbox allows you to send and receive pre-approved template messages to numbers that join your Sandbox, using a shared Twilio test number.

To explore the Sandbox, visit the "Learn" section for WhatsApp in the Twilio Console.

Using WhatsApp in production

We provide an approval process to help you determine if your use case is eligible for using WhatsApp in production with your own number and profile, and submit for approval if so. Please complete the Request Access form to submit your request.

If your vertical or use case is not listed as an option in the form, your use case is not currently eligible for WhatsApp approval. You will also need to provide a Facebook Business Manager ID in order to submit your application. If you don't already have an ID, create an account at business.facebook.com.

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. Once approved by WhatsApp, you'll be able to submit your own templates for approval for use in production.

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 customer care, notifications, and mixed use cases over Twilio. WhatsApp does not allow promotional or marketing use cases, and will not approve Templates with promotional content.

  • Customer Care is 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 Session messages (non-template). The conversation will remain open for 24hrs from the last message received from the user.
  • Notifications use case is a uni-directional messaging service designed for the business to send alerts and informational notifications to users. Messages sent in this use case are required to use pre-approved Templates.
  • Mixed use case is initiated when a user replies to a notification message, thus starting a customer care use case.

 

Send a message to a WhatsApp user

To send a WhatsApp message, your application needs to make an HTTP POST request to Twilio’s Programmable SMS Message REST API resource with three required pieces of information; A recipient, a sender, and your message.

  • 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).
  • Message: The Body parameter consisting of the desired message you wish to send.
    • New outbound messages must be sent using pre-approved templates. Responses within 24hours have no template requirement. See Messaging Capabilities above for more information.

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 "Body=Your appointment is coming up on {{Date}} at {{Time}}" \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will contact the destination (310) 555-5555 from the sender (212) 555-1234 via the WhatsApp app, and send the following message:

Your appointment is coming up on {{Date}} at {{Time}}

To make this script work for you, make the following updates, and then paste it into a terminal window:

  • Line 1 update with your Account SID
  • Line 2 update with a valid destination
  • Line 3 update with a valid sender number
  • Line 4 update with your desired message
    • New outbound messages must be sent using pre-approved templates. Responses within 24hours have no template requirement. See Messaging Capabilities above for more information.
  • Line 5 update with your Account SID and Auth Token.

Additional Resources

Have more questions? Submit a request
Powered by Zendesk