Have you been thinking about using WhatsApp API for business but don't know what it is or how it works? This ultimate guide to WhatsApp Business API answers all your questions. We'll cover what is WhatsApp API, how to manage contacts and send messages according to WhatsApp's best practices.
WhatsApp Business API Account Basics
WhatsApp has two products - WhatsApp Business App & WhatsApp Business API. We’ve outlined the product differences in our WhatsApp Business blog. In this guide, we are only focusing on the technical aspects of WhatsApp API and what it means to businesses.
For a start, the WhatsApp API is designed for medium to larger companies in mind. Since it’s an API, there is no app and front-end interface. Instead, it requires end-users to take the WhatsApp API endpoint and integrate it into their business software.
WhatsApp is particular with who it allows connecting to their API directly. At this point, it has only given access to a handful of large companies like Singapore Airlines, Uber and Wish.
Rather, businesses wanting to connect to WhatsApp API are encouraged to use third-party services called Business Solution Providers (BSPs) or WhatsApp Partners. It’s easier to get approved for a WhatsApp API account by applying through them.
WhatsApp Business Solution Providers
Today there are more than 60 official WhatsApp Business API Solution Providers on Facebook’s directory. Your experience may differ radically depending on your BSP. To simplify things, there are two types of WhatsApp BSPs - SMS providers and Others.
The first group are SMS providers like Twilio and Vonage. As SMS providers, these companies are already using their proprietary APIs before they started selling WhatsApp accounts. Hence, the API you need to connect to will be similar to their Legacy SMS API.
These BSPs are great for businesses who are already using their service and wish to integrate WhatsApp API as one of their communication channels. It allows businesses to use multiple chat platforms without having to connect everything themselves.
The ease of applying for an account depends on your BSP. For instance, Twilio have a self-service platform that allows you to get started without talking to anyone. While Vonage is more enterprise-oriented and requires you to talk to sales.
But because these SMS providers are integrating WhatsApp API with their proprietary API, it takes more time and effort on their end to include or update any new features from WhatsApp.
Next, we have the other groups that do not identify as SMS providers. Although WhatsApp started with SMS providers as BSPs, there are other companies that received partnerships like CRM vendors, chatbot agencies and self-service bot platforms.
These types of WhatsApp Busines Solution Providers like 360dialog are more likely to use a proxy API. Because their API is similar to WhatsApp’s, it is fast and easy for them to enable new features via WhatsApp API.
This means that their API is essentially redirecting to WhatsApp API and has the same API infrastructure. If you want new updates to reflect quickly on your WhatsApp account, then consider a BSP using a proxy API.
In this guide, we’ll be discussing all the features available directly from WhatsApp API. You can use it as a reference when shopping for BSPs. Before we go into the specifications, we’ll look at WhatsApp API’s pricing and profile.
WhatsApp Business API Pricing
To recap, you have to sign up with a BSP and pay them to get a WhatsApp API account. And as the middlemen, BSPs have to pay WhatsApp on their end to connect to their API so they can provide the service to end-users.
Essentially, BSPs pay WhatsApp a price that is different from what they actually charge businesses. And because every BSP can set their own pricing, it makes sense to find out if you’re actually getting a bang for your buck.
Generally, WhatsApp does not charge BSPs anything for messages sent within 24 hours (Session Messages) but there’s a small fee for messages sent after 24 hours (Message Templates).
However, some BSPs charge end-users for both Session Messages & Message Templates. By using the Message Template rate card charged by WhatsApp to the BSPs, it will be easier for you to negotiate a deal because you know exactly how they’re charged.
Plus, this isn’t the final WhatsApp pricing. Starting in February 2021, WhatsApp will be experimenting with its pricing model in Mexico. For more details and comparisons between BSP pricing, we have a detailed guide in our WhatsApp Pricing article.
WhatsApp Business API Profile
Now that you know the role of BSPs in setting up a WhatsApp API account for you, it’s time to look at how a WhatsApp API business profile looks like. The WhatsApp API profile is not so much different from the WhatsApp Business App profile.
Unlike other messaging apps, the WhatsApp API profile will not be searchable in-app, so it is up to the business to promote their presence. Businesses can optimize their profile by updating their cover photo, description, address, email and website.
Most WhatsApp Business accounts will be listed as a Business Account. Very rarely a business will be given an Official Business Account unless it’s a large company like Nike or Coca-Cola. These accounts have a WhatsApp verified green tick next to their name.
Getting verified is hard, but not impossible. Here is an overview of how to do it. Some BSPs allow editing your profile or apply for verification on a self-service platform, while the others require sending API calls. So take this into account when choosing a BSP.
For the rest of this article, we'll be discussing what is technically possible by calling the various APIs WhatsApp makes available. These include the Contacts API and Messages API.
WhatsApp Business API Contact Management
WhatsApp has stringent requirements when it comes to starting a chat with WhatsApp users. Generally, WhatsApp prefers that end-users message your account first to start a conversation.
Even so, WhatsApp allows companies to send their customers the first message as long as they follow a set of rules. Next, we’ll cover these rules as well as some features available via WhatsApp API to make Contact Management on your application smoother.
WhatsApp does not want businesses to spam customers with unwanted messages. To maintain the quality of customer experience, WhatsApp requires businesses to obtain opt-ins or gain active consent from users prior to messaging them first.
The opt-in policy is only required for transactional notifications or messages sent after 24 hours (Message Templates). For the exact opt-in rules and guidelines, refer to this document by WhatsApp.
To start, there are many ways businesses can obtain opt-ins, both on and off WhatsApp. This includes interactive voice response (IVR), website forms, WhatsApp Ads, WhatsApp links, WhatsApp QR codes or through WhatsApp threads (customer-initiated messages).
For contacts to opt-in, they must first see the value of doing so. It’s best to ask them to do it at the right time and right place. For instance, if you have a SaaS platform you could ask them to opt-in to receive new feature updates when they sign up for an account.
Once they’ve opted in, avoid messaging too frequently or they might just opt-out. Or worse, they might mark your business as spam affecting your account’s quality rating. Now that you know how contact opt-in works, let’s talk about managing contacts.
Verifying and Importing Contacts
Although contacts are not stored on WhatsApp API, we’ll discuss the possibilities of verifying and importing contacts via the API features. To start, you’ll need to verify if your contacts have a valid WhatsApp ID or WhatsApp number.
This is important because sending messages to WhatsApp numbers that don’t exist will lower your account rating. Conversely, if you check too many numbers without sending messages your account will be banned. This is likely to avoid spammers on the platform.
After verifying your contacts, you can then import them to a CRM platform. While WhatsApp did not mention much about importing contacts in their documentation, we’ve covered how to do so in this article.
Once you've imported your contacts to a CRM platform, you can manage those contacts with some additional features offered by WhatsApp.
User Identity Notification
Upon opting-in to user ID notifications, businesses will be alerted whenever they receive messages from a re-registered WhatsApp account. Businesses should be aware of re-registered accounts as it means another user has taken over their contact’s number.
These notifications inform businesses if they are sending information to the right person. Unless businesses acknowledge the re-registration, they are blocked from sending messages to these accounts.
But in some cases where the business blocks a contact by choice, these contacts can still message the business by changing their number. While this opt-in feature is not foolproof, it is still a good effort at:
- Protecting both businesses and customers from leaking sensitive information over WhatsApp.
- Preventing businesses from getting flagged as spam lest they try messaging the wrong person/user that did not opt-in to their notifications.
To prevent getting flagged, WhatsApp has made it possible for businesses to monitor their account and message quality rating. Businesses can ensure the quality of customer experience by following WhatsApp's messaging best practices and guidelines.
WhatsApp API: Messaging Best Practices and Guidelines
For a start, WhatsApp Business API doesn’t allow you to send a message anytime or in any format you want. Instead, businesses wanting to message with WhatsApp API have to play by the rules which are designed to prevent spam.
For instance, you can only freely message people within 24 hours (Session Messaging) and they can only send transactional notifications after 24 hours (Template Messaging). Plus, Message Templates are content that needs to be pre-approved by WhatsApp.
It's important to understand and adhere to these WhatsApp messaging rules to maintain your phone number rating and phone number quality.
To drive higher quality conversations, WhatsApp API provides businesses with insights into your phone number quality rating and status. You can find these quality insights via the Business Manager API.
These ratings indicate how WhatsApp views conversation quality with your business. Businesses have to ensure they are sending only high-quality Message Templates to avoid getting their number blocked or reported by their contacts.
Contacts have the option to choose the reason for blocking such as No Longer Needed, Didn't Sign Up, Spam and so on. Other notable reasons beyond this list include how often the business sends notifications and the time it takes for them to reply to inquiries.
When blocked, your phone number quality rating will drop from high (green) to medium (yellow) or low (red). Consequently, your phone number will be moved to a Flagged status when your number quality rating is low (red).
Once it improves to medium or high in 7 days, your phone number status will return to Connected. If your quality rating does not improve in 7 days, WhatsApp will still reinstate your status to Connected but impose a lower messaging limit on your number.
Messaging Capacity and Limit
The messaging limit is related to your phone number quality and status. It determines how many unique users your business are allowed to message daily, including new and existing conversations with users.
However, messaging limit does not apply to the number of messages sent in response to a user-initiated message within 24-hours (Session Messages). Only the number of users you’re trying to message and notification messages (Message Templates) will be limited.
In summary, WhatsApp imposes three tiers of messaging limits on businesses. Businesses start at Tier 1 upon registering their phone number. According to WhatsApp’s documentation, your business account:
- Starts - Tier 1: Allows your business to send messages to 1K unique contacts in a rolling 24-hour period.
- Then - Tier 2: Allows your business to send messages to 10K unique contacts in a rolling 24-hour period.
- Finally - Tier 3: Allows your business to send messages to 100K unique contacts in a rolling 24-hour period.
Businesses can upgrade their phone number to the next tier if their quality rating is not low. And the total number of users it sends notifications to must add up to twice their current messaging limit within a 7-day period.
For instance, if you message a total of 2,000 users within a 7-day period your WhatsApp phone number will be upgraded from Tier 1 to Tier 2. If your business sends up to the current limit every day, it takes a minimum of 48 hours for the upgrade to occur.
To monitor your phone number's quality, you can now subscribe to receive notifications when there is:
- A change in your phone number status from Connected to Flagged and vice versa.
- An upgrade or downgrade to your number’s messaging tier.
That's not all. To further improve messaging quality and overall customer service experience, WhatsApp has recently introduced a new policy to include a human agent pathway within a chat.
WhatsApp Human Escalation
Unsurprisingly, customers dislike chatting with bots especially if they have an issue that needs to be sorted out with a human agent. WhatsApp has finally acknowledged this pain point and made it compulsory for a WhatsApp Human Escalation pathway.
From November 2020, WhatsApp may reactively review bot experiences directly on the platform. During these reviews, WhatsApp will initiate conversations with the bot and record these messages for quality monitoring purposes. Fret not, they will clearly indicate in the thread when they are doing so.
Some acceptable escalation methods include human agent handoff, phone number, email, web support form and prompting in-store visits. However, indirect channels such as social media, a help centre webpage or a link to an app do not meet this requirement.
Without a human escalation pathway, your phone number quality rating may become low (red) and your phone number status will be Flagged. You’ll receive the warning via an update from your Business Manager and through your registered email.
If it remains unresolved in 7 days, WhatsApp will restrict your messaging limit. Businesses sending below 1,000 notifications a week will not see an immediate impact. But to increase the messaging limit in the future, you’ll have to resolve this issue first.
Types of WhatsApp Business API Messages
Now that you know how your phone number quality rating and status affect your messaging limit, we’ll discuss the two types of messages allowed on WhatsApp API - Session Messages and Message Templates.
WhatsApp API Session Messages
As we know, WhatsApp is particular about how businesses interact with customers. To ensure businesses reply to incoming messages quickly, WhatsApp imposes a messaging limitation called Session Messaging for API account users.
Session Messaging allows you to reply to contacts’ messages within a 24-hour window. Once the 24-hour window closes, you can no longer use Session Messages to reply to customers. Also, you cannot use Session Messages to message a contact first.
Even so, businesses do get some flexibility with using Session Messages. There is no need for any prior approval before sending a message as long as it abides by WhatsApp Business Policy and WhatsApp Commerce Policy.
Whenever a contact starts a chat, businesses can reply to that user without any restrictions including the number of messages and type of content. By default, WhatsApp API allows the following Session Message format:
- Text messages (supports formatting such as bold, italic, strikethrough & code)
- Text messages with URL (can enable preview URLs & all URLs are clickable)
- Media messages (audio, document, image, sticker & video)
Although these message types are supported by WhatsApp API, the exact features you’ll get depend on whether your BSP provides them. Every BSP is different, so check with them first if they support the type of message you need.
Once the Session Messaging window closes, businesses will only be able to send Message Templates to their contacts.
WhatsApp API Message Templates
After 24 hours from the contact’s last incoming message, businesses are only allowed to reply with Message Templates. Alternatively, businesses can start a new conversation with contacts that have opted-in using Message Templates.
However, sending a Message Template is not as straightforward as sending a Session Message. Every Message Templates have to be submitted to your chosen BSP for approval before you can use and send them.
Till recently, businesses can only use WhatsApp API to send bulk messages in the form of transactional notifications. For instance, delivery and account updates. Any non-transactional and broadcast notifications like recurring newsletters are not allowed.
But things are changing from October 2020. WhatsApp has started rolling out non-transactional notifications in countries like Indonesia & Mexico. More recently, WhatsApp has expanded the list to include Brazil, Spain, Malaysia, United States & more.
To be eligible, businesses must have an accepted country’s address in their Facebook Business Manager registered with WhatsApp. Businesses can unlock this capability with no extra integration work and the Message Template creation process remains the same.
Depending on your business needs, WhatsApp API supports different types of Message Templates such as text, media and interactive Message Templates. But like Session Messages, the exact messaging feature depends on what your chosen BSP provides.
Now that you know how Template Messaging works, we’ll discuss the best practices when creating a Message Template for approval from your BSP.
Message Templates Best Practices
To avoid your Message Templates from getting rejected, it’s best to familiarize yourself with the dos and don’ts when creating a Message Template. Your BSP has the right to reject your templates for any of the reasons discussed below.
Formatting and Language
Your Message Templates have to be in the correct format. Incorrect formatting including misspellings and grammatical errors could give the wrong signal that your message is spammy and untrustworthy.
Next, the language selected must be supported and match the content of your Message Templates. If you select Hindi as your message’s language but the content is in English, it’ll get rejected. A mixture of languages such as “Hinglish” will also not be approved.
If you want to include a URL, the domain in your link must belong to your business. However, WhatsApp also does not recommend using a URL shortener such as bit.ly, tinyurl etc because they obscure the intended link destination.
A workaround is to use the URL in your placeholder instead of the template. WhatsApp only checks and approves the templates and not the placeholder where it's editable.
From a business perspective, we would recommend using a URL shortener as it helps businesses and marketers to:
- Track links and add UTMs without making it too long. Essentially, UTMs are codes you add to the end of a regular URL to inform Google Analytics of the source and marketing campaign it belongs to.
- Know how many clicks there are and understand the behaviour of people you sent the link over a messaging app.
Also, URL previews do not show by default. This feature depends on your BSP, so double-check with them if you need this feature. If you’re using a proxy API, you'll need to add an extra line of code to tell the API you’re sending a URL with a preview.
Message Templates Quality Rating & Status
To sum it up, it’s best to abide by these guidelines. Message Templates that do not meet WhatsApp’s standards may prompt contacts to block you. When blocked, your Message Template quality will drop to low and it changes your template status to Flagged.
If your template quality does not improve from low to medium or high in 7 days, WhatsApp will disable your templates and you can no longer edit or send them out. You’ll be notified via email when your template’s status changes to Flagged or Disabled.
To prevent this, ensure that your contacts have opted-in according to WhatsApp’s guidelines. Avoid sending too many notifications in a day and make sure your content is highly relevant and useful for them.
WhatsApp Business API Infographic
If you're interested in more information about WhatsApp for Business, why not check out these articles: