Twilio API for WhatsApp Best Practices and FAQs

With Twilio Programmable Messaging, you can integrate WhatsApp messaging into your web application. Although those integrations are generally straightforward, we see some common questions about how best to utilize the Programmable Messaging API, specifically for WhatsApp. We've also found some common patterns and best practices that'll get you sending WhatsApp messages sooner.

Following are answers to frequently asked questions and some of our best practices for your integration of the Twilio API for WhatsApp.

Frequently Asked Questions on WhatsApp Integrations

General

• What are the requirements for a business to be approved for WhatsApp?
  
  WhatsApp requires compliance with the WhatsApp Business Solution Terms, with the WhatsApp Business Solution Policy and with their Commerce Policy. As part of the approval process, the business and use case are being considered to make sure the usage is in line with the above guidelines.
  

• What is the cost of the WhatsApp service?
  
  WhatsApp service is being charged per message fees. There are two types of messages: Notification messages are being charged with WhatsApp fee and Twilio fees. Customer Care messages are being charged with Twilio fees. You can find more information about the cost of sending WhatsApp messages here.

• How can I manage separate access list to Sandbox and to the live numbers on my account?
  
  If you have the need to segment traffic and manage separate access list, we recommend that you break the traffic between different Twilio accounts. This will allow you to have better control over each one of the use cases and will allow managing separate access list of each.

• My implementation is for the European market. Is it GDPR compliant?

  Twilio is committed to GDPR compliance. We offer GDPR ready Data Protection Contract terms. To add a DPA addendum please fill our Twilio GDPR Data Protection Addendum Request.

Sandbox

• Why am I getting a message "your number is not associated with the sandbox channel"?
  
  Be sure you follow the instructions in the Using Phone Numbers with WhatsApp section of the API Reference and Overview carefully. You'll need to join a sandbox, as well as enable one of your Twilio numbers with WhatsApp.
  
  
• Why am I getting a message "Twilio could not find a Channel with the specified From address" when trying to send a message?
  
  There are 2 common reasons why you are seeing this error :
  • The `From` address in your Messaging API request is incorrect. To send messages using WhatsApp, the `From` address should be `whatsapp:<sandbox phone number>`. This can be found on the sandbox page here.
  • You are trying to send a message from an account that does not have that sandbox installed. Please activate the sandbox before sending a message using it.

• I joined the Twilio sandbox for WhatsApp and got a "Twilio Sandbox. You are all set! The sandbox xyz can send/receive messages..." reply. Can I change the message?
  
  This Sandbox reply message is part of our sandbox implementation and cannot be changed. Once you get your own number, you are free to set your own implementation. Just keep in mind that WhatsApp requires brands to receive customer opt-in before sending messages on WhatsApp.

• My outbound message from the Sandbox was not delivered. Why?
  
  There are 2 reasons why a message sent from the Twilio Sandbox for WhatsApp would fail to be delivered :
  1. You are trying to send a message to a user who has not joined your sandbox. See here for instructions on how they can join your sandbox.
  2. You are sending a free form message outside the WhatsApp session to the user. A WhatsApp session lasts for 24 hours after the last inbound message you receive from a user. Outside a WhatsApp session, you may only send a pre-approved template message to the user (see here for more details); any message that doesn't match a pre-approved template will be sent by Twilio as a free form message. See a list of templates pre-approved for the sandbox here.

API

• Can I check if a user's phone number is enabled for WhatsApp?
  
  Every time you send a WhatsApp message, Twilio automatically checks if the number is enabled for WhatsApp and will fail the message with error code 63003 if the destination was found to be invalid. WhatsApp has strict guidelines when it comes to checking for availability. When a number is found a valid WhatsApp number, it is required to follow up with a message to avoid getting the account marked for lower quality traffic. Our implementation makes sure to protect your quality rating when using WhatsApp.

• What formatting options do I have in WhatsApp?
  
  Your messages can be bold, italicized, struck-through, or preformatted.
  
  

  Formatting	Symbol	Example
  Bold	Asterisk (*)	Your total is *$10.50*.
  Italic	Underscore (_)	Welcome to _WhatsApp_!
  Strike-through	Tilde (~)	This is ~better~ best!
  Code / Pre-formatted	Three backticks (```)	```print 'Hello World';```

  
  The text inside the formatting symbols will take on the format you choose.

• Can I send messages to WhatsApp groups or manage groups?
  
  Currently, our API does not support messaging with or managing WhatsApp groups. We expect to add support for groups in the future.

Live Phone Numbers

• What use cases are supported by WhatsApp?
  
  WhatsApp supports two use cases: Customer Care and Notifications. Customer Care is initiated with an inbound message. When the first message is received from the user, it opens a conversation, in which the business can reply back with freeform messages. 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. WhatsApp restricts marketing/promotional use cases and will not approve Templates with promotional content.

• Can I mix Notifications and Customer Care use cases?
  
  Yes. Each WhatsApp number supports both use cases. When the user replies to a Notification, the incoming message starts a Customer Care use case, allowing the business to send freeform messages. Notification messages can be sent during a conversation window, and in between conversation windows.

• Is it possible to port an external number outside of Twilio to use WhatsApp?
  
  At this time, you need a Twilio number enabled for WhatsApp in order to send messages using the Twilio API for WhatsApp. This can be any Twilio number which has voice or SMS capabilities. In the future, we expect to be able to offer the ability to enable WhatsApp Business profile on your own, non-Twilio numbers as well. Meanwhile, for information on porting your numbers to Twilio, see these help article: https://support.twilio.com/hc/en-us/articles/223179348-Porting-a-Phone-Number-to-Twilio

• What account type options do I have for my business in WhatsApp? How do they appear in the app?
  
  Information about available WhatsApp account types can be found here. You can apply for Official Business Account once your number is live and the Facebook Business Manager account that is linked to your WhatsApp number is set to Verified status.

• What kind of phone numbers can be enabled for WhatsApp?
  
  WhatsApp requires a phone number to be e.164 compliant and be able to receive an OTP code via SMS or phone call to be enabled. Most numbers sold on Twilio are supported, with the exception of toll-free numbers outside of the US.

Setting up a Business Profile

• What is the process to get a live number set for WhatsApp?
  
  The process includes the following steps: approval, numbers set up, templates submission and account verification.
• Step 1: Approval - fill out this form to request access. Applications are processed on a weekly basis. Customers submitting the form to request access during the week will hear back from us in the following week via email with an updated status. As part of the application, you will be requested to provide your Twilio Account SID and FB Business Manager ID. While we may be able to process partial applications, they are likely to introduce delays in set up.
• Step 2: Numbers set up - once you have received an email notification, go to WhatsApp Senders page in Console to create your WhatsApp Business Profile. You will need to use a Twilio number to do that. If you do not yet have a Twilio number set on your account, you can purchase one here. Submitting a WhatsApp Business Profile will create a support ticket with our WhatsApp ops team and your application will be processed. We will provide updates on the number set up via the ticket system.
• Step 3 - Template Approval - If you plan to send out Notifications, you will need templates approved on your account. You can find information about the use of Templates and Notifications use case here. Once templates are submitted, please follow up with a ticket to our support team, requesting to process the templates added. Templates need to be approved by WhatsApp before being used, in a process that takes a few days. Note that WhatsApp does not provide an SLA for this review. Based on our experience, it takes about 5 days to get templates approved.
• Step 4 - Account Verification - businesses that send Notifications may benefit from an Official Business Account. You can find information about how to request account verification and limitations here.

Media Support

• How can I send and receive media on WhatsApp? What type of media is supported?
  
  You can find information about how to send and receive media messages and supported media on WhatsApp here. A more detailed, step-by-step tutorial for sending and receiving media on WhatsApp can be found here.

Troubleshooting WhatsApp Error Codes

• I'm getting error code 63020 when trying to send messages on WhatsApp. What should I do?
  
  Error 63020 indicates that you have yet to accept the invitation from Twilio to send messages on your behalf on the business. Please go to FB Business Manager account and accept the invitation to be able to send and receive messages.

• Everything went well until I started receiving error code 63018 when I try to send messages. Why?
  
  Error 63018 indicates that you have hit the rate limit set on your WhatsApp number. You can learn more about WhatsApp rate limit and how to plan your rollout around it here.