WhatsApp Cloud Integration
Comparing with other messaging platforms, WhatsApp has a stricter requirement and here're a few things you should pay attention to when you plan to create digital presence on WhatsApp Business.
Introduction
WhatsApp Cloud API helps businesses onboard and build their first official WhatsApp messaging experience. Different from the WhatsApp business app on smartphone, WOZTELL has integrated with WhatsApp Cloud API and allows our users to create chatbot through our platform. Registering as a business will unlock features such as:
- Business Information: People can now easily identify your business by its category or industry and find out more information (i.e., hours of operation, website, address, description).
- Send and Receive: Enable two-way high value conversations with customers.
- Message Templates: Create message formats that are needed for sending notifications to users.
Conversations
With the WhatsApp Cloud API, the usage and charges are measured based on the concept of Conversations.
A conversation is measured in fixed 24-hour sessions, it starts when the first business message in a conversation is delivered, either initiated by the business or in reply to a user message.
The businesses will be charged per 24-hour conversation. Within a 24 hour conversation session, businesses and users can exchange any number of free form messages or template messages under the same category without additional charges, given that the messages being sent do not initial a new conversation of another category.
Conversation Categories
| Category | Type | Description |
|---|---|---|
| Utility | Business-initiated | Facilitate a specific, agreed-upon request or transaction or update to a customer about an ongoing transaction, including post-purchase notifications and recurring billing statements |
| Authentication | Business-initiated | Enable businesses to authenticate users with one-time passcodes, potentially at multiple steps in the login process (e.g. account verification, account recovery, integrity challenges) |
| Marketing | Business-initiated | Include promotions or offers, informational updates, or invitations for customers to respond / take action. Any conversation that does not qualify as utility or authentication is a marketing conversation. |
| Service | User-initiated | Messages sent by the business in response to the customers' enquiries. |
Pricing
Starting from 01/06/2023, the conversation charges will vary based on the template category. When a template is delivered, it opens a new chargeable conversation under that category, unless the template is delivered during an open conversation of the same category. Multiple templates of the same category within an open conversation will not result in additional charges.
Service conversations will still only be initiated when no other conversation window is open and a business responds with a free form message within the 24-hour customer service window.
Example
Scenario 1:
Sending a marketing template inside a marketing conversation.
Chargeable Conversation:
One marketing conversation.
Scenario 2:
Sending a free form message inside a service conversation.
Chargeable Conversation:
One service conversation.
However, if a template of a different category is sent within an open conversation, a separate chargeable conversation will be opened.
If a business replies with a template message in an open service conversation, this will also create a separate conversation based on the template category.
Example
Scenario 1:
Sending a marketing template inside an utility conversation.
Chargeable Conversation:
One utility conversation and one marketing conversation.
Scenario 2:
Sending a authentication template inside a service conversation.
Chargeable Conversation:
One service conversation and one authentication conversation.
The only exception is the Free Entry Point conversations, which allow businesses to send multiple templates of different categories within free window and no new conversation will be opened.
The rates for business-initiated and user-initiated conversations vary by country or region. For the detailed rates, please refer to the rate cards.
Free Entry Point
A Free Entry Point conversation is initiated when:
- A customer using a device running Android or iOS messages the business via a Click to WhatsApp Ad or Facebook Page Call-to-Action button; and
- The business respond within 24 hours
If you do not respond within 24 hours, a free entry point conversation is not opened and you must use a template to message the customer.
The free entry point conversation is opened as soon as your message is delivered and lasts 72 hours. When a free entry point conversation is opened, it automatically closes all other open conversations between you and the customer, and no new conversations will be opened until the free entry point conversation expires.
Once the free entry point conversation is opened, you can send any type of message to the customer without incurring additional charges. However, you can only send free-form messages if there is an open customer service window between you and the customer.
Example Scenario
If the customer messages you via a Click to WhatsApp Ad at 10am and you respond via a template message at 10pm the same day:
- The free-entry point conversation starts at 10pm and lasts 72 hours.
- You can send template messages at no charge in those 72 hours.
- You can send free-form messages until 10am the next day, at which point the customer service window closes, as it is independent of the free entry point conversation (if the customer messages you again, however, it opens another 24 hour customer service window in which you can send free form messages).
Reminder
Although the business will be not charged for the free entry point conversation, but the business still needs to pay for the ad itself.
Free Tier
Changes to Free Tier Conversations: Effective June 1, 2023 This will not apply to businesses managed by Business Solution Providers, or businesses that did not rely on the services of a Meta partner to integrate the On-Premises API, until June 1, 2023. For all other accounts, this takes effect on April 1, 2023.
Each WhatsApp Business Account (WABA) can receive free tier conversations of 1000 user-initiated conversations each month, which is independent of the number of phone numbers attached to the WABA. The business-initiated conversation is not covered by the free tier. The free tier will be refreshed monthly based on the timezone associated with the WABA.
Reminder
This will not apply to businesses managed by Business Solution Providers, or businesses that did not rely on the services of a Meta partner to integrate the On-Premises API, until June 1, 2023.
For all other accounts, this takes effect on April 1, 2023.
Message Template
Message Templates are message formats for common reusable messages a business may want to send. Businesses must use Message Templates for sending notifications to customers. This allows a business to send just the template identifier along with the appropriate parameters instead of the full message content. Message templates will be submitted for review before being able to be sent, in order to ensure they do not violate the WhatsApp policies.
Supported Categories
Reminder
- The following categories are supported in v1.1.0 or later versions.
- Under the new conversation-based pricing model, the conversation charge will vary based on the template category used to initiate a conversation.
| Category | Description |
|---|---|
| Authentication | Send codes to verify a transaction or login. |
| Marketing | Send promotions or information about your products, services or business. |
| Utility | Send messages about an existing order or account. |
Reminder
- The following categories are only supported in v1.0.0
- WhatsApp Cloud API will deprecate the following categories on May 1, 2023
| Category | Description |
|---|---|
| Marketing | Send promotional offers, product announcements, and more to increase awareness and engagement. |
| One-time passwords | Send codes that allow your customers to securely access their accounts. |
| Transactional | Send account updates, order updates, alerts, and more to share important information. |
Supported Languages
The following are some of the supported languages for message templates. You can refer to here for the full list.
| Language (A-K) | Code | Language (L-Z) | Code |
|---|---|---|---|
| Afrikaans | af | Lao | lo |
| Albanian | sq | Latvian | lv |
| Arabic | ar | Lithuanian | lt |
| Azerbaijani | az | Macedonian | mk |
| Bengali | bn | Malay | ms |
| Bulgarian | bg | Malayalam | ml |
| Catalan | ca | Marathi | mr |
| Chinese (CHN) | zh_CN | Norwegian | nb |
| Chinese (HKG) | zh_HK | Persian | fa |
| Chinese (TAIWAN) | zh_TW | Polish | pl |
| Croatian | hr | Portuguese (BR) | pt_BR |
| Czech | cs | Portuguese (POR) | pt_PT |
| Danish | da | Punjabi | pa |
| Dutch | nl | Romanian | ro |
| English | en | Russian | ru |
| English (UK) | en_GB | Serbian | sr |
| English (US) | en_US | Slovak | sk |
| Estonian | et | Slovenian | sl |
| Filipino | fil | Spanish | es |
| Finnish | fi | Spanish (ARG) | es_AR |
| French | fr | Spanish (MEX) | es_MX |
| Georgian | ka | Spanish (SPA) | es_ES |
| German | de | Swahili | sw |
| Greek | el | Swedish | sv |
| Gujarati | gu | Tamil | ta |
| Hausa | ha | Telugu | te |
| Hebrew | he | Thai | th |
| Hindi | hi | Turkish | tr |
| Hungarian | hu | Ukrainian | uk |
| Indonesian | id | Urdu | ur |
| Irish | ga | Uzbek | uz |
| Italian | it | Vietnamese | vi |
| Japanese | ja | Zulu | zu |
| Kannada | kn | ||
| Kazakh | kk | ||
| Kinyarwanda | rw_RW | ||
| Korean | ko | ||
| Kyrgyz (Kyrgyzstan) | ky_KG |
Status
Message Templates can have the following statuses:
| Status | Description |
|---|---|
| In-Review | Indicates that the template is still under review. Review can take up to 24 hours. |
| Rejected | The template has been rejected during our review process or violates one or more of our policies. See Appeals. |
| Active - Quality pending | The message template has yet to receive quality feedback from customers. Message templates with this status can be sent to customers. |
| Active - High Quality | The template has received little to no negative customer feedback. Message templates with this status can be sent to customers. See Quality Rating. |
| Active - Medium Quality | The template has received negative feedback from multiple customers but may soon become paused or disabled. Message templates with this status can be sent to customers. |
| Active - Low Quality | The template has received negative feedback from multiple customers. Message templates with this status can be sent to customers but are in danger of being paused or disabled soon, so we recommend that you address the issues that customers are reporting. |
| Paused | The template has been paused due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers. |
| Disabled | The template has been disabled due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers. |
| Appeal Requested | Indicates that an appeal has been requested. |
You will notified of the status changes by subscribing to the Message Template Status Update.
Quality Rating
Each message template has a quality rating based on usage and customer feedback. The rating is available on the templates which has the Active status. The quality rating includes:
| Quality Rating | Color |
|---|---|
| Quality pending | Green |
| High | Green |
| Medium | Yellow |
| Low | Red |
Approved message templates start out with a Quality pending rating. When message template has the Active status, it can be sent to end users. If a message template continuously receives negative feedback, it will affect the quality rating, and eventually result in the change in status, the template will be not allowed to be sent until the status becomes active again.
For more details, please refer to Quality Rating.
Template Pausing
If a message template reaches the low quality rating, it will be paused for a period of time to protect the quality rating of phone numbers that have used the template:
- 1st Instance: Paused for 3 hours
- 2nd Instance: Paused for 6 hours
- 3rd Instance: Disabled
When a message template is paused, it can't be sent to end users until it is back to be Active again.
Alternatively, you can edit the paused template content in order to reduce the negative feedback it might receive. However, once you submitted the edited template, it needs to be reviewed by the WhatsApp team. If the edited template is approved and status is back to Active, you can start sending this template again.
Template pausing initially does not affect the business phone number. However, if a business is continuously sending low quality message templates, the phone number might be impacted.
For more details, please refer to Template Pausing.
Opt-in
A user must first consent to receive messages in WhatsApp by opting into them via WhatsApp or a third-party channel. This can be any channel your business uses to communicate with people today — your WhatsApp thread, interactive voice response (IVR) flows, website, app, email, SMS, retail location, etc.
You must follow the below requirements when obtaining opt-in:
- You must clearly state that a person is opting in to receive messages from the business over WhatsApp
- You must clearly state the business’ name that a person is opting in to receive messages from
- You must comply with applicable law
You should continue to optimize for the user experience while obtaining opt-in. For example, you should:
- Explicitly call out the types of messages a person is opting into (e.g., delivery updates)
- Avoid messaging people too frequently
- Provide instructions for how customers can opt out and honor these requests
- Monitor your quality rating, especially when rolling out new opt-in methods
For detailed opt-in requirements, please refer to WhatsApp Opt-in Guidelines.
Official Business Account
There are two types of WhatsApp Business Accounts:
| Name | Description |
|---|---|
| Official Business Account | WhatsApp has verified that an authentic brand owns this account. An Official Business Account has a green checkmark badge in its profile and next to the header in the chat thread. The name of the business is visible even if the user hasn't added the business to their address book. Very few businesses will be an Official Business Account. Being verified on Facebook or Instagram will not help your business be an Official Business Account. |
| Business Account | Any account that is using the WhatsApp Business API is by default a Business Account. |
If the WhatsApp Account is an Official Business Account, the Verified Name will be visible in the chat list, chat screens, chat groups, and contacts view instead of the phone number. There will be a
To apply for an Official Business Account, WhatsApp requires businesses to complete Business Verification and enable Two-step Verification during WhatsApp Account Registration.
Business Verification
You will have to complete verification for your Facebook Business Manager, please refer to the steps given here. Once your business is verified, you will be able to see your business verification status as "verified".
Two-step Verification
You will also need to set up a code for two-step verification. You can create your two-step verification PIN right before the deployment of your WABA number.
Rate Limit
Messaging Limit
Messaging limits determine how many unique users your business can send messages to on a daily basis.
- Tier 1: Allows your business to send messages to 1K unique customers in a rolling 24-hour period
- Tier 2: Allows your business to send messages to 10K unique customers in a rolling 24-hour period
- Tier 3: Allows your business to send messages to 100K unique customers in a rolling 24-hour period
- Tier 4:Allows your business to send messages to unlimited unique customers in a rolling 24-hour period.
For details, please click here.
Throughput
The Cloud API supports up to 80 messages per second (mps) by default and up to 1,000 mps by request. Throughput is inclusive of inbound and outbound messages and all message types.
Reminder
If you would like to request for higher throughput limit for your phone number, please submit your request to support@woztell.com