Ultimate Guide

WhatsApp API: The Ultimate Guide to WhatsApp Business API (Jan 2021)

By January 19, 2021April 23rd, 2021No Comments
WhatsApp API: The Ultimate Guide to WhatsApp Business API (Jan 2021)

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.

Looking to use WhatsApp with multiple users? You'll need a WhatsApp API account. Apply now for the cheapest WhatsApp API account on the market and start messaging customers in just 10 minutes with Express Sign-Up!

WhatsApp API Explained

WhatsApp API Account Basics

Contact Management

Messaging Best Practices & Guidelines

Types of WhatsApp Business API Messages

WhatsApp Business API Infographic

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.

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.
WhatsApp Business API is Best for Medium to Large Companies

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.

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.
Types of WhatsApp Business API Partners

SMS Providers

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.

Others

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.

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.
WhatsApp API Pricing

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 (Template Messages).

However, some BSPs charge end-users for both Session Messages and Template Messages. By using the Template Message 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 comparison 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.

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, website and business hours.
WhatsApp Business API Profile

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.

Contact Opt-In

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 (Template Messages). For the exact opt-in rules and guidelines, refer to this document by WhatsApp.

The opt-in policy is only required for transactional notifications or messages sent after 24 hours (Template Messages). Businesses can obtain opt-in in many ways, both on and off WhatsApp.
WhatsApp API Contact Opt-In

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 by making sure they have a valid WhatsApp ID, you might be interested to know how to import them to a CRM platform.
Verifying and Importing WhatsApp Contacts

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.

When a contact’s identity changes, businesses can choose to be notified when a contact’s WhatsApp number is re-registered.
WhatsApp API User Identity Notification

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:

  1. Protecting both businesses and customers from leaking sensitive information over WhatsApp.
  2. 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, Template Messages 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.

Quality Rating

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 Template Messages to avoid getting their number blocked or reported by their contacts.

When blocked, your WhatsApp phone number quality rating will drop from high (green) to medium (yellow) or low (red).
WhatsApp Business API Phone Number Rating

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).

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.
WhatsApp Business API Phone Number Status

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 (Template Messages) will be limited.

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 (Template Messages) will be limited.
WhatsApp Business API Messaging Capacity and Limit

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.

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.
Upgrade Phone Number from Tier 1 to Tier 2

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.

WhatsApp has made it compulsory for businesses to include a human agent within a chat thread. Failure to do so affects your phone number rating and status.
WhatsApp Human Escalation Pathway

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 Template Messages.

There are two types of messages allowed on WhatsApp API - Session Messages and Template Messages.
Types of WhatsApp Business API Messages: Session Messages & Template Messages

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. Businesses cannot use Session Messages to message a contact first, nor can they reply to the contact after 24 hours.

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.

Session Messaging allows you to reply to customers’ messages within a 24-hour window. Businesses cannot use Session Messages to message a contact first, nor can they reply to the contact after 24 hours.
WhatsApp Business API Session Messaging

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)
  • Contacts
  • Location

Although these message types are supported by WhatsApp API, the exact features you’ll get depends 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 Template Messages to their contacts.

WhatsApp API Template Messages

After 24 hours from the contact’s last incoming message, businesses are only allowed to reply with Template Messages. Alternatively, businesses can start a new conversation with contacts that have opted-in using Template Messages.

However, sending a Template Message is not as straightforward as sending a Session Message. Every Template Messages 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 promotional content and broadcast notifications like recurring newsletters are not allowed.

After 24 hours from the contact’s last incoming message, businesses are only allowed to reply with Template Messages. Alternatively, businesses can start a new conversation with contacts that have opted-in using Template Messages. Only transactional messages are allowed and every template has to be approved by your WhatsApp Business Solution Provider first.
WhatsApp Business API Template Messaging

But things are changing from October 2020. WhatsApp has started rolling out non-transactional notifications in countries like Indonesia and Mexico – with more countries to come. This includes templates with promotional or marketing content.

To be eligible, businesses must have a Mexico or Indonesia address in their Facebook Business Manager registered with WhatsApp. Businesses can unlock this capability with no extra integration work and the Template Message creation process remains the same.

Depending on your business needs, WhatsApp API supports different types of Template Messages such as text, media and interactive Template Messages. 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 Template Message for approval from your BSP.

Template Messages Best Practices

To avoid your Template Messages from getting rejected, it’s best to familiarize yourself with the dos and don’ts when creating a Template Message. Your BSP has the right to reject your templates for any of the reasons discussed below.

Formatting and Language

Your Template Messages 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 Template Message. 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.

To get approved, Template Messages must be in the correct format and the selected language must match the message's content.
WhatsApp Business API Template Messages Best Practices

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.

Template Messages Quality Rating & Status

To sum it up, it’s best to abide by these guidelines. Template Messages that do not meet WhatsApp’s standards may prompt contacts to block you. When blocked, your Template Message quality will drop to low and it changes your template status to Flagged.

WhatsApp will rate your Template Messages quality rating as low, medium or high. Low-quality template messages will be flagged or disabled.
WhatsApp Business API Template Messages Quality & Status

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

This infographic outlines all you need to know about using WhatsApp Business API.

Further Reading

If you're interested in more information about WhatsApp for Business, why not check out these articles:

WhatsApp API: The Ultimate Guide to WhatsApp Business API (Jan 2021)
Serene Tan

Serene Tan

Serene is the Content Lead at respond.io. She was an ex-teacher with stints in Australia, Singapore and Japan before returning home. She's also an MBA graduate from the University of Wales Trinity St David, UK and a certified social media marketer from Digital Marketing Institute.

33 Shares
Share via
Copy link
Powered by Social Snap