WhatsApp Cloud API
Connecting a WhatsApp Cloud API account to chat with customers over WhatsApp.
PreviousTurn-off WhatsApp Number Two-Step VerificationNextMigrating from On-Premises API to Cloud API
Last updated
Connecting a WhatsApp Cloud API account to chat with customers over WhatsApp.
Last updated
Facebook announced the release of WhatsApp Cloud API on 20th May, and it’s available to any business of any size, big and small to communicate with customers using the official WhatsApp API.
To chat with your customers over WhatsApp Cloud API, connect a WhatsApp Business Profile and Facebook Business account.
Facebook App and Facebook Business Account are required and you must be the admin of both to connect.
Step 1: Navigate to Workspace Settings > Click Add Channel
Step 2: Locate the WhatsApp Cloud API Channel > Click Connect..
Step 3: Click the Connect With Facebook button.
Step 4: Sign in using the Facebook account with admin access to the Facebook App and Meta business account.
Step 5: In the dropdown list, select the WABA name with the WhatsApp number you would like to connect.
Step 6: Add the Callback URL. Go back to the WhatsApp section in Facebook Developer App. Navigate to the Configuration subsection and set up the Callback URL. Add the generated Callback URL and verify the token from IS-Messenger to the corresponding fields at the webhook dialog
Step 7: On the Facebook App, verify and save changes to the app.
Step 8: Subscribe to the webhook event. On your Facebook App, select the Webhooks tab under the Products panel and select WhatsApp Business Account in the dropdown list. Click on subscribe messages event.
Step 9: Click the toggle at the top of the page to turn on live mode.
Remember to fill in your privacy policy URL. If this is blank, you will not be allowed to turn on live mode.
Step 10: Click Save Changes to complete the setup.
Press DONE to complete the setup.
Once you have completed the setup, any messages sent to your WhatsApp number will now be received in your Space.
Step 1: Navigate to Workspace Settings > Click Channels.
Step 2: Locate the WhatsApp Cloud API Channel > Click Manage.
Step 3: Configure the Channel name, which is used internally to identify the account.
Step 4: Click Save Changes to update the channel configuration.
Different channels provide different set of Contact’s metadata to IS-Messenger platform. Here’s the list of Contact’s data you’ll be able to obtain from this channel:
Phone number
Phone number ID
Profile name
Whatsapp ID
Step 1: Navigate to Workspace Settings > Click Channels.
Step 2: Locate the WhatsApp Cloud API Channel > Click Manage > Profile.
Step 3: Click Sync Profile to obtain the latest WhatsApp Business Profile information from WhatsApp.
Step 4: Edit the following information as needed.
Profile Photo
Image shown as the profile picture of the WhatsApp Business Account
An image size of 640x640 is recommended
Address
Address of the business. Maximum of 256 characters.
Description
Description of the business. Maximum of 512 characters.
Email address (in valid email format) to contact the business. Maximum of 128 characters.
Vertical
Industry of the business. Must be one of these accepted values:
Automotive
Beauty, Spa and Salon
Clothing and Apparel
Education
Entertainment
Event Planning and Service
Finance and Banking
Food and Grocery
Public Service
Hotel and Lodging
Medical and Health
Non-profit
Professional Services
Shopping and Retail
Travel and Transportation
Restaurant
Other
The business vertical cannot be set back to an empty value after it is created.
Website
URLs (including http:// or https://) associated with the business (e.g., website, Facebook Page, Instagram). Maximum of 2 websites with a maximum of 256 characters each.
Step 5: Review the information and click Save Changes.
Before sending a message template to a Contact on the IS-Messenger platform, ensure you've done the following:
Submitted the message template for approval
Added the approved message template to the Workspace by syncing the message template
Step 1: Navigate to Workspace Settings > Click Channels.
Step 2: Locate the WhatsApp Cloud API Channel > Click Manage.
Step 3: Click Templates > Submit Template to submit a message template for approval.
Step 4: Fill in the required information needed to create a template.
Field
Description
Template Name
The name can only contain lowercase alphanumeric characters and underscores ( _ )
Category
The category to which the message template belongs.
Language
The language that the template is written in.
Step 5: Create the message by filling in the necessary components, then review the message in the preview section. You may include parameters {{1}}, {{2}}, etc. as placeholders to be filled in with personalized content.
Building Block
Description
Body
The Body contains the most important text of your template. Only text is supported.
You may use markdown to format the content of this block.
Header
The Header is optional and serves as the title or header of your template. It supports the following:
Text
Image
Video
Document
*Respond.io platform accepts uploads up to 20MB in size.
Footer
The Footer is optional and only supports text. It can be used to provide supplementary information in your message template.
Button
The Button is optional and adds interactivity to your templates. There are two types available:
Call To Action Button
Used to send your client to a Website or call a Phone Number
Maximum one URL and Phone Number per template
URL can have a parameter or personalization
Quick Reply Button
Used to get quick answers from your client
Maximum 3 Quick Reply buttons per template
Each Quick Reply button cannot have more than 20 characters
Step 6: Provide sample value
This is only applicable if you have included any parameters in your message template content.
Providing sample values to the parameter in the message template will assist the WhatsApp reviewer in understanding the message you are trying to send to your Contacts.
Step 1: Navigate to Channel Settings From Settings Module, navigate to the menu item, Channels
Step 2: Locate the WhatsApp Cloud API channel Once you have located the WhatsApp Cloud API channel, press Templates
Step 3: Submit Template Press Submit Template to submit a Message Template for approval
Step 4: Fill in the required information Fill in the information needed to create a new template
Name
The name can only contain lowercase alphanumeric characters and underscores ( _ )
Category
The category of which the message template belongs to.
Language
The language that the template is written in.
Step 5: Start building the message
Create the message by filling in the necessary components, then review the message in the preview section. You may include parameters {{1}}, {{2}}, etc. as placeholders to be filled in with personalized content.
Header
The Header is optional and serves as the title or header of your template. It supports the following:
Text
Image
Video
Document
*IS-Messenger Platform accepts uploads up to 20MB in size
Body
The Body should contain the most important text of your template. Only text is supported.
You may use markdown to format the content of this block
Footer
The Footer only supports text and can be used to provide less relevant information in your template message
Button
The button adds interactivity to your templates. There are two main types.
Quick Reply Button
Used for getting quick answers from your client
Max 3 Quick Reply Buttons per Template
Each Quick Reply cannot have more than 20 characters
Call to Action Button
Used to send your client to a Website or call a Phone Number
Max one URL and Phone Number per Template
URL can have a parameter for personalisation
Step 6: Providing sample value This is only applicable if you have included any parameters in your message template content.
Syncing Message Templates
Step 1: Navigate to Workspace Settings > Click Channels.
Step 2: Locate the WhatsApp Business Platform (API) channel > Click Manage.
Step 3: Click Templates > Sync Template to begin the syncing process.
The following table lists the possible statuses for the message templates:
Status
Description
Submitted
The message template is submitted and pending approval.
Approved
The message template is approved and can be sent to contacts.
Rejected
The message template is rejected and cannot be used.
The file type supported by WhatsApp and the maximum file size for the type is as follows:
Audio & Video (16MB)
Document (100 MB)
Image (5 MB)
Sticker (100 KB)
Messages that are not supported will have a fallback display with Unsupported Message or Custom Payload text and Type (if available). For any unsupported file type or file that exceeds the maximum file size sent via WhatsApp Cloud API, the file will automatically be turned into a URL link on the respond.io platform. For Custom Payload, you can click Show More to view the JSON payload of this message. Examples of unsupported messages for WhatsApp Cloud API are: - Contact Card - Reactions - Deleted Message - Polls - Ephemeral Message
Make sure that the number you connected to the platform is a WhatsApp Cloud API number.
Step 1: Navigate to Facebook App Webhook page Open the Facebook App and navigate to the Webhooks page.
Step 2: Verify the subscribed event Select Whatsapp Business Account and verify if messages event is subscribed.
Step 3: Send a test message Send a test message to the WhatsApp phone number and check if it arrived.
Step 1: Navigate to Channel Settings From Settings Module, navigate to the menu item, Channels
Step 2: Locate the WhatsApp Cloud API channel Once you have located the WhatsApp Cloud API Messenger channel, press Troubleshoot
Step 3: Refresh Permission Press Refresh Permission to refresh WhatsApp permissions.
Step 4: Send a test message Send a test message to the WhatsApp phone number and check if it arrived.
This can happen due to a few reasons:
When the session for validating the access token has expired.
There was a change to the user's admin privilege in Meta Business Manager.
There was a password change on Meta Business Manager.
You must be the admin of the Meta Business Manager to be able to refresh permission.
If your contacts cannot receive message from your WhatsApp Cloud API number, make sure that they have agreed to the latest WhatsApp terms and privacy policy.
Unable to Send Messages
Make sure that the number you've connected to the platform is a WhatsApp Cloud API number.
Messages Are Not Arriving
Step 1: Navigate to the Facebook App Webhook page
Open the Facebook App and navigate to the Webhooks page.
Step 2: Verify the subscribed event
Select Whatsapp Business Account and verify if the messages event is subscribed.
Step 3: Send a test message
Send a test message to the WhatsApp phone number and check if it arrived.
When the user connected to WhatsApp Cloud API changes their Facebook password, the permissions will be outdated and need to be refreshed.
Step 1: Navigate to Workspace Settings > Click Channels.
Step 2: Locate the WhatsApp Business Platform (API) channel > Click Manage.
Step 3: Click Troubleshoot > Refresh Permission to refresh WhatsApp permissions.
Step 4: Send a test message to the WhatsApp phone number and check if it arrived.
Unable To Send Outbound Messages: Validating Access Token Error
This can happen due to a few reasons:
When the session for validating the access token has expired.
There was a change to the user's admin privilege in Meta Business Manager.
There was a password change on Meta Business Manager.
You must be the admin of the Meta Business Manager to be able to refresh permission.
If your Contacts cannot receive messages from your WhatsApp Cloud API number, make sure that they have agreed to the latest WhatsApp terms and privacy policy.
What are the requirements for phone number to be used to sign up for WhatsApp Cloud API?
The phone number used for WhatsApp Cloud API can't be used in the WhatsApp personal or business app. You'll have to delete the account on the WhatsApp personal or business app before you can use the number to sign up for awhatsApp Cloud API.
You can still use the number for other purposes, such as calling and receiving SMS after registering it on the WhatsApp Business Platform.
Once you use a phone for WhatsApp Cloud API you can no longer use that number on the WhatsApp Business App.
If the number is already being used in the WhatsApp customer or business app, you will have to delete your account on the WhatsApp customer or business app.
The Phone number used for WhatsApp Cloud API can’t be used in the WhatsApp customer or business app.
You can still use the number for everyday purposes, such as calling and receiving messages after registering it on the WhatsApp Business Platform.
Once you use a phone for WhatsApp Cloud API you can no longer use that number on the WhatsApp Business App.
It isn’t mandatory to complete Facebook business verification to start sending messages on WhatsApp. Without business verification, your business will still be able to
Respond to unlimited customer-initiated conversations.
Send business-initiated conversations (template messages) to 50 unique customers in a rolling 24-hour period. You will need to complete business verification if you want to initiate more than 50 business-initiated conversations in a rolling 24-hour period.
Businesses can initiate Business Verification (BV) only when they are ready to scale business-initiated conversations or want to become an Official Business Account.
You can send a test broadcast from the platform using the Meta test number. However, a broadcast using the test number is limited to five recipients. You must first add these five recipients to the phone number list in the Meta Developer tools.
If you do not add recipients to this list or if you attempt to send a broadcast to recipients not on this list, you will receive this error message:
No, this number is automatically provided to all accounts to use for sending test messages and cannot be deleted. Just be careful to note that this is a test number not to be used for other purposes.
Navigate to Your FBM > WhatsApp Account > Phone Number. This page displays your messaging limit and quality.
Hover over the pencil icon next to the display name to enable editing.
Click Next to submit your new display name to Meta for approval.
Await confirmation of approval from Meta.
After receiving approval from Meta for your new display name, complete the following steps:
Re-register your phone number using the newly approved display name.
Once successful, your Cloud API's display name update is complete.
WhatsApp Business Platform conversations fall into two categories that are priced differently:
All conversations are measured in fixed 24-hour sessions. A conversation starts when the first business message in a conversation is delivered, either initiated by the business or in reply to a user message. Businesses and users can exchange any number of messages, including template messages, within a 24 hour conversation session without incurring additional charges. Each 24 hour conversation session results in a single charge.
This channel has a limited 24-hour messaging window due to WhatsApp regulations. Find out more !
Important Link:
Important Link:
You may use to fill in the message template parameter.
A rate limit is the number of API calls an app or user can make within a given time period defined by the channel. Learn more about the
To solve this error, you must and send a test message again.
Having trouble with the channel? Contact us !
To solve this error, you must and send a test message again.
Yes, you can monitor your messaging and spending analytics in real-time for your WhatsApp business account in the Insights tab of your Meta WhatsApp Manager. Read more .
There are a few requirements and steps needed to delete a phone number, read more
Messaging limits determine the maximum number of business-initiated conversations each phone number can start in a rolling 24-hour period. These limits do not apply to user-initiated conversations. A business-initiated conversation starts when the first message is delivered to a customer and ends 24 hours later. Read more .
WhatsApp passes the Contact’s phone number in that IS-Messenger uses. This difference causes Contacts from certain countries to be duplicated. Should this occur, do .
To , follow these steps:
Execute a POST API call to .
Make another POST API call to
This is most likely due to you exceeding the monthly free tier threshold without a valid payment method. To resolve this issue, .
Your first 1,000 conversations each month are free. If you want to exceed the free tier of 1,000 conversations per month, you need to add a payment method to your WhatsApp Business account in Business Manager. You can learn more
User-initiated: A conversation that initiates in response to a user message. Whenever a business replies to a user within the 24 hour , that message will be associated with a user-initiated conversation. Businesses can send free-form messages within this 24 hour customer service window.
Business-initiated: A conversation that initiates from a business sending a user a message outside the 24 hour customer service window. Messages that initiate a business-initiated conversation will require a .
Charges for conversations are based on the user’s country code. A user here is defined as the customer that your business is communicating with. Rates for business-initiated and user-initiated conversations vary by country or region. Read more
Effective June 1, 2023, there will be changes to the conversation-based pricing for WhatsApp. Learn more about these .
There are a few requirement and steps needed to delete a phone number, read more
