The WhatsApp Business API with Twilio: Best Practices and FAQs

With Twilio Programmable Messaging, you can integrate WhatsApp messaging into your web application. Although those integrations are generally straightforward, we often get asked 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.

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

Frequently asked questions

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 its Commerce Policy. As part of the approval process, the business and use case will be considered to make sure the usage is in line with the above guidelines.
  
  
• What is the cost of the WhatsApp service?
  
  WhatsApp service is charged per message fees. Meta also charges fees per 24 hour window for each conversation which are passed on to you by Twilio. There are two types of conversations: Business-initated conversations and user-initated conversations. You can find more information about the cost of sending WhatsApp messages here.
  
  
• How can I manage separate access lists to Sandbox and to the live numbers on my account?
  
  If you have the need to segment traffic and manage separate access lists, we recommend that you split the traffic between different Twilio accounts. This will allow you to have better control over each one of these use cases and will allow you to manage separate access lists for each account.
  
  
• What is the MPS (Messages Per Second) limit for outbound WhatsApp messages?
  
  

  The WhatsApp Business API with Twilio has a maximum messaging throughput of 25 MPS (messages per second) per sender for outbound traffic containing text-only. The maximum throughput for outbound traffic containing media files is 1.5 MPS.

  When your application sends WhatsApp messages to Twilio at a rate that exceeds the limits above, Twilio maintains a queue and dispatches messages from this queue at the respective rates of 25 MPS and 1.5 MPS for text-only messages and messages containing media (see guidance on supported file types). This message queue has a maximum limit of four hours. Messages that remain in the queue for more than four hours will fail. New messages that will cause the queue to back up beyond the four hour time limit will be rejected and fail.

  Many factors may impact the actual rate at which WhatsApp messages are delivered to the end recipients. Examples include sending large media files, sending high volumes of unique media files to each recipient user, sending messages containing URLs to websites with long load times, receiving concurrent inbound messages on the same WhatsApp number that is sending outbound notifications, and high network latency between servers and recipient users. To avoid unexpected queue buildup and elevated message failures, it is recommended that you don't send message requests at rates at or exceeding the aforementioned limits for sustained periods of time.

  To achieve higher MPS for your sending needs, you can use Messaging Services. This allows you to distribute high message volumes across many senders within a messaging service.

  If you have high throughput requirements for your use case, please contact our support team for guidance on best practices and assistance on your individual requirements.

• My implementation is for the European market. Is the API GDPR compliant?
  
  Twilio is committed to GDPR compliance. We offer GDPR-ready Data Protection Contract terms. To add a suitable Data Protection 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 Programmable Messaging 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 two common reasons why you are seeing this error:
  • The From address in your Programmable 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.
    
    
• 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 reply is part of our sandbox implementation and cannot be changed. Once you get your own number, you are free to set your own message. 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 two reasons why a message sent from the Twilio Sandbox for WhatsApp would fail to be delivered:
  • You are trying to send a message to a user who has not joined your sandbox. Please see our instructions for getting started with the sandbox, including how users can join your sandbox.
  • 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 (for more details read up on template messages); any message that doesn’t match a pre-approved template will be sent by Twilio as a free-form message. You can find a list of templates pre-approved for the sandbox here.

API-specific questions

• 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 prevent the account from being marked for lower quality traffic. WhatsApp does not allow exposing the capability check and using that independently of sending a message.
  
  
• What formatting options do I have in WhatsApp?
  
  See our guide to rich messaging features, including formatting, in the WhatsApp Business API with Twilio.
  
  
• Can I send messages to WhatsApp groups or manage groups?
  
  WhatsApp deprecated the Groups API in April 2020. Twilio offers a group messaging solution using the Conversations API. You may reference this sample code in CodeExchange: WhatsApp Group Messaging. For more info, please refer to Twilio Conversations.
  
  
• Does the WhatsApp Business API with Twilio support read receipts?
  
  Twilio supports read receipts on business-initiated messages. Currently, Twilio does not support read receipts for inbound (user-initiated) WhatsApp messages. This means it is not possible for the business to set the status of a message it received to "read" (i.e., changing the checkmark color on the end user's application).

Live Phone Numbers

• What use cases are supported by WhatsApp?
  
  WhatsApp supports user-initiated and business-initiated messaging. With user-initiated messaging, the first message is received by the business from the user. This opens a conversation in which the business can reply back with free-form messages. The conversation remains open for 24 hours following the last message received from the user.
  
  Business-initiated messaging is when the business sends the first message to the user, or replies to the user more than 24-hours after the last message received from the user. This typically applies to notification use cases. Business-initiated messaging requires the use of pre-approved templates.
  
  
• 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 FB 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 to be able to receive an OTP (one-time PIN) code via SMS or phone call (to enable the service). Most numbers sold on Twilio are supported. More info can be found here.

Setting up a Business Profile

• What is the process to get a live number set for WhatsApp?
  
  Please see our step-by-step guide to setting up and connecting a WhatsApp Business Profile to your Twilio Phone Number.

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. We also have a more detailed, step-by-step tutorial for sending and receiving media on WhatsApp.

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 your 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’s rate limit and how to plan your rollout around it here.