CleverTap WhatsApp Business API

Understand how to integrate the WhatsApp channel using CleverTap.

🚧

Private Beta

Currently, this feature is in private beta and is available only for enterprise customers. If you want access to this feature, contact your account manager.

Overview

CleverTap is an official WhatsApp Business Service Provider (BSP). You can access WhatsApp business API directly from the CleverTap dashboard and start creating WhatsApp campaigns within a few minutes after WhatsApp onboarding. CleverTap's WhatsApp Business API removes the dependency of having any external WhatsApp BSP integration to use the WhatsApp channel with the CleverTap dashboard.

Prerequisites For WhatsApp Onboarding

Listed below are the prerequisites to get started with WhatsApp onboarding with CleverTap BSP.

  • You need a verified Facebook Business Manager page to access advanced WhatsApp features. To verify your account, you must submit a few vital documents. Click here for more information about the list of documents required at a country level for account verification.

For non-verified pages, businesses can still have restricted access for up to 30 days.

🚧

Admin Access

It is mandatory for the user proceeding with the WhatsApp onboarding on CleverTap to have admin access to the Facebook Business Manager page.

  • Ensure that you provide a dedicated WhatsApp number for long-term use, as this number can not be changed later. This number must be a new number and should not be active on personal WhatsApp or Business WhatsApp applications.
  • Ensure that your WhatsApp number is active, as you will receive an OTP for verification during the onboarding process.
  • While onboarding, ensure that you enter your display name the same as the one used on the Facebook business manager page (also known as the legal name). If the display name doesn't match the business name, you must provide a web URL that showcases proof of association in the header/footer.
  • Lastly, ensure that your business meets Facebook's commerce policy.

❗️

Unique WhatsApp Number

You must use a distinct WhatsApp number for each CleverTap project.

Integrate WhatsApp using CleverTap BSP

To integrate WhatsApp using CleverTap BSP, follow the steps below:

  1. Navigate to Settings > Channels > WhatsApp from the CleverTap dashboard.
  2. Click + Provider and select CleverTap BSP from the Provider dropdown.
  1. Read all the prerequisites and click Continue with Facebook.

  2. To register and connect your WhatsApp business account with CleverTap:

    i. Create or select your Meta and WhatsApp Business Account.
    ii. Create your WhatsApp Business profile.
    iii. Verify your WhatsApp Business number.

After completing the registration, your business is reviewed within 24 hours for compliance with WhatsApp's commerce policy.

  1. After your onboarding is successful, you must complete the setup on the CleverTap dashboard.
11341134
  1. Select your WABA Name, Nickname, and mobile number to complete the setup.

  2. Click Save and Complete Setup

📘

Note

After completing the WhatsApp onboarding process, businesses can immediately:

  • Send business-initiated conversations to 250 unique customers in a rolling 24-hour period.
  • Register up to two phone numbers until the WABA display name is approved. Once the display name is approved you can add up to 50 numbers.

Creating WhatsApp Message Templates

You must create new message templates for WhatsApp communications in your WhatsApp Business Manager Account provided by Facebook. To get started with template creation.

  1. Log in to your Facebook Business Manager account.
28682868
  1. Open the hamburger menu available at the top of the page and select WhatsApp Manager. The WhatsApp Business accounts page opens.
  2. Click Message templates from the left navigation menu under Account tools as shown below. The list of templates is displayed, where you can see all of your existing templates along with their status and quality ratings.
26182618
  1. Click Create Template. The template creation page opens.
  2. Select the Category, Name, and Language as shown below:
    • Category: Select the type of template you want to create. You can hover over the template types to view details for each template.
    • Name: Enter the template's name in lowercase letters, numbers, and underscores only.
    • Language: Select the languages for your message template. You can delete or add more languages in the next step.
  3. Click Continue after filling up all the required details.
27162716
  1. Define the overall content for the WhatsApp template message as shown below.
28802880
  1. (Optional) Click Add Sample to add an optional content example for your template. This helps in understanding the type of message you want to send during the review and approval process.

❗️

Sample Content for Template

Ensure that the sample content that you add does not include any actual user or customer information.

  1. Click Submit.

Your template is now sent for review. The status of your template is visible under Message templates. After your message is approved, you can copy the message template and paste it into the CleverTap dashboard. To learn more about the template creation process, refer to this detailed document by Facebook.

📘

Pre-Approved Message Templates

Facebook offers some pre-approved WhatsApp message templates for testing. You can use these templates in the CleverTap dashboard to start sending test messages as soon as you complete WhatsApp onboarding.

Add Message Template

To create WhatsApp campaigns, you must have pre-approved WhatsApp message templates saved in the CleverTap dashboard. To add the templates:

  1. Navigate to Settings > Channels > WhatsApp.
  2. Select the provider Nickname from the CleverTap dashboard.
  3. Select the Templates tab, and click +Template.
21642164
  1. Enter the template name in the Namespace field.
  2. Select the type of template header (Text or Media). For Media headers, you can use Image, Video, Document, and Location.
  3. Enter the message content.
  4. (Optional) You can add a Footer text and a Button (Quick Reply or a Call To Action).
  5. (Optional) You can choose the message language.
20362036
  1. Click Save Template.

Testing a Message Template

You can send a test message using the saved templates from the CleverTap dashboard as follows:

  1. Hover over the desired template for which you want to send a test notification.
  2. Click Send Test.
  3. Select the test profiles or manually enter the mobile number to whom you want to send the test message and click Send Test.
13041304

The success or failure response is displayed on the dashboard. If the message is not delivered, you can copy the response payload and share it with the CleverTap team to debug the issue, as shown in the following figure.

728728

Create a Campaign

To create a WhatsApp campaign using CleverTap BSP, refer to this detailed document on How to create a WhatsApp Campaign.

Create a Journey

To create a WhatsApp journey using CleverTap BSP, refer to this detailed document on How to Create a WhatsApp Journey.

FAQs

Onboarding

Q. What is Facebook business manager account verification?
A. As the prerequisite for WhatsApp onboarding explains, your Facebook business manager account needs to be verified to get full WABA access. Facebook business verification is the way for Facebook to know that your business is a legitimate organization. Your business must be registered as per the business registration process of your country.

Q. Do I need to verify the Facebook manager account again if it is already verified?
A. Facebook business verification is also required for other purposes, along with getting WABA access. Given this, there are chances that you have already verified your business manager account. You do not have to go through the verification process if your account is verified.

Q. How do I check if my Facebook business manager account is verified or not?
A. To check if your Facebook business manager account is verified, open your Facebook business manager account and navigate to Settings. Scroll down and click Security Settings. If your Business manager account is verified, the "Security Center" section displays as follows:

Q. What are the requirements for business verification?
A. To verify the business manager account, you must fill in the business details. Ensure that the information provided aligns with the details registered with local authorities. As long as Facebook can verify your organization from the given information, there is no need to provide supporting documents for verification. To check the exact requirements for verification in your country, refer to the detailed documentation

Q. My Facebook business manager is not verified; how do I get it verified?
A. Follow the steps given in this document to understand the steps required for getting your Facebook business manager account verified.

Q. How long does Facebook take to verify the business manager account?
A. Facebook takes a few weeks to verify the business manager account. This is subjective to how soon Facebook can verify your documents and can take longer in some cases.

Q. What happens if I complete WhatsApp onboarding without business verification?
A. Previously, businesses could not send any messages before completing the account verification. This meant if verification took a few weeks, they had to wait that long to start using the WhatsApp Business APIs.

While waiting for verification, businesses can use the unverified trial experience (sandbox) to test the functionality. During the trial experience, businesses are allowed to initiate a conversation with a limited number of users, but the business can respond to unlimited incoming chats. Read more.

Q. Are there any repercussions if I do not verify the Facebook business manager account?
A. It is important to start your Facebook Business verification as soon as possible. In most cases, the account is verified the same day as the process starts, but in some cases, this may take some time. If the business is not verified by Facebook or approved as per WhatsApp commerce and display name policy within 30 days, the number goes offline.

Q. What are the best practices for WhatsApp display names?
A. Do not add extra words, spaces, or special characters to your company or brand name used in the business display name. To learn more, refer to the document.

Q. I have completed onboarding; how do I check if my WABA account/display name is approved?

A. Display approval happens after your business is verified, so if you have not verified your business yet, start the verification at the earliest.

To check your display number approval status, open your Facebook business manager account and navigate to WhatsApp business manager from the hamburger icon in the left navigation bar. Now, select the WhatsApp account associated with the number for which you want to check the display name approval status, and then click Phone numbers from the left navigation bar under Account tools.

18521852

Now, click View under Certificate. If your display name is approved, the Display name has an Approved tag in front of it, as shown below:

13581358

Q. How do I check my current messaging limit?
A. To check your current messaging limits, open your Facebook business manager account and navigate to WhatsApp business manager from the hamburger icon in the left navigation bar. Further, select the WhatsApp account associated with the number for which you want to check the Display name approval status and then click Phone numbers from the left navigation bar under Account tools. Your messaging limit appears under Messaging limit in the phone numbers table.

28762876

Q. How do I increase the messaging limit?
A. To learn about the messaging limit levels, refer to this detailed document by Meta.

Message Templates

Q. What are message templates?

A. As explained earlier, there are two types of conversations - user-initiated and business-initiated. In the case of user-initiated conversations, you can send any text to end-users. However, if your business initiates the conversation, you can only send the message reviewed and approved by Facebook. These approved text messages are called Message templates.

Q. How much time does Facebook take to review the templates?
A. It can take up to 24 hours for approval. Once approved, a notification appears in your WhatsApp Manager, and we send an email to your Business Manager admins. In addition, we also send a webhook notification if you subscribe to message template status changes. Learn more about Monitoring Status Changes.

Q. Are there any best practices for message templates?
A. Facebook expects you to create templates for genuine use cases and not violate their policy. There is no single correct approach to creating templates but following these basic guidelines will help in getting your templates approved quickly and customers also enjoy interaction with your business.

  1. Templates should be short, simple, and have only the necessary text to pass on the required information to the customer.
  2. Templates must not have any grammatical or spelling mistakes. Templates that include major spelling or grammatical mistakes are likely to be rejected. Templates with minor punctuation errors or grammatical inconsistencies may be approved but should be avoided.
  3. Be mindful of formatting errors. Ensure that you are not missing any sequence in variables ie. {{1}},{{3}},{{4}} or used the curly braces properly in dynamic variables.
  4. Title of the template should explain how the template is going to be used. for example, if you are creating a template for sending booking information, the title should be booking_update. Also, note that the title can not be changed later so name the templates in such a way that it is easier to identify your templates easily.
  5. if plan to use any redirection URLs, ensure that you provide full URLs. Using short URLs in templates might cause templates to be rejected.
  6. Use the same language in the template content that you chose in the template language field. you chose Arabic as the template language then write template content in Arabic.

Refer to these detailed documents by Facebook to learn more about the best practices for WhatsApp message templates.

Q. How do I create new templates?
A. Refer to the Add Message Template section.

Q. What are the common reasons for template rejection?
A. Listed below are the common reasons for template rejections:

  • Variable parameters are missing or have mismatched curly braces. The correct format is {{1}}.
  • Variable parameters contain special characters such as a #, $, or %.
  • Variable parameters are not sequential. For example, {{1}}, {{2}}, {{4}}, {{5}} are defined but {{3}} does not exist.
  • The message template contains content that violates WhatsApp's Commerce Policy.
  • The message template contains content that violates WhatsApp's Business Policy.
  • The content contains potentially abusive or threatening content, such as threatening a customer with legal action or threatening to shame them publicly.
  • The message template is a duplicate of an existing template. If a template is submitted with the same content in the body and footer of an existing template, the duplicate template is rejected. A rejection email notification, including the rejection reason that appears in Account Quality on WhatsApp Manager, is sent. You may refer to the Account Quality notification to see the name and language of the existing template with the same content as the rejected duplicate template. You may also choose to edit the template and resubmit. Please note that this check does not apply to OTP templates.

Q. Can I edit the templates after they are approved?
A. You can edit a template using the WhatsApp Manager or the Message Template endpoint. Note that if you edit a message template and resubmit it for approval, its status changes to In Review and cannot be sent to customers until its status changes to Active.

Q. What is template quality, and how do I check the quality of my templates?
A. To check the quality rating of your templates, open your Facebook business manager account and navigate to WhatsApp business manager from the hamburger icon in the left navigation bar. Further, select the WhatsApp account associated with the number for which you want to check the template quality rating, and then click on Message templates from the left nav bar under account tools. Your messaging limit will show up under messaging limit in the phone numbers table.

28802880

Q. What are common template statuses?
A. Templates can have the following statuses:

  • In-Review: Indicates that the template is still under review. Review can take up to 24 hours.
  • Rejected: Indicates that the template has been rejected during the review process. Learn more.
  • Active - Quality pending: Indicates that the message template is yet to receive quality customer feedback. Message templates with this status can be sent to customers. Learn more about Quality Rating.
  • Active - High Quality: Indicates that the template has received little or no negative customer feedback. Message templates with this status can be sent to customers. Learn more about Quality Rating.
  • Active - Medium Quality: Indicates that 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. Learn more about Quality Rating.
  • Active - Low Quality: Indicates that 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 report. Learn more about Quality Rating.
  • Paused: Indicates that the template has been paused due to recurring negative customer feedback. Message templates with this status cannot be sent to customers. Learn more about Template Pausing.
  • Disabled: Indicates that the template has been disabled due to recurring negative customer feedback or for violating one or more of our policies. Message templates with this status cannot be sent to customers. You may be able to edit a disabled message template and request an appeal. Learn more.
  • Appeal Requested: Indicates that an appeal has been requested. Learn more

Number Quality

Q. What is number quality and connection status?
A. Your quality rating indicates how template messages have been received by your users in the last 24 hours. There are three different states of messaging quality:

  • Green: High quality
  • Yellow: Medium quality
  • Red: Low-quality

If your Quality rating remains Red for seven or more days, your number's connection status changes to Flagged or Restricted.

  • Flagged: Indicates that the quality rating has reached a low state. Businesses can not upgrade messaging limit tiers during the Flagged phase. If the message quality improves to a high or medium state by the seventh day from when your status was moved to Flagged, the status changes to Connected. If the quality rating does not improve, the status still changes to Connected, but you are placed in a lower messaging limit tier.
  • Restricted: Indicates that you have reached your messaging limit. During a Restricted phase, you can not send any notification messages until the 24-hour window is reset. However, you can respond to any messages that customers initiate. Learn more.

Q. How do I check my number quality?
A. Navigate to Facebook business manager and open WhatsApp business manager. Further, click Phone number under Account tools. This will show you the number quality and status of your numbers.

19101910

Q. What to do if the number quality is Red? How to improve Quality Rating?
A. Follow the guidelines below to improve your Quality Rating:

  • Reduce the WhatsApp campaigns for a week and send only important notifications and target your champion user base only.
  • Ensure that your templates comply with the WhatsApp Business Policy.
  • Ensure that your messages are clear, personalized, and useful to users.
  • Avoid sending open-ended welcome or introductory messages.
  • Only send template messages to users that have opted in to receive messages on that specific topic. For example, if a user opted-in for COVID updates but starts receiving other health updates, they may respond negatively because they did not opt-in for that specific communication.
  • Be mindful of your messaging frequency. Avoid sending users too many notifications in a day.
  • Be thoughtful of informational messages, and optimize the content and the message length.
  • Check if your organization has added and sent a new template within the last 7 days. This may help determine a problematic template(s).

Number Migration

Q. I want to migrate my number from CleverTap to external BSP; what is the process?
A. Please contact your account manager to seek support for the migration process or raise a ticket with our support team from your CleverTap dashboard.

Q. I want to migrate numbers from external BSP to CleverTap BSP; how do I get this done?
A. Please contact your account manager to seek support for the migration process.
Also, refer to this document to know more about the migration process.