WhatsApp Cloud Bot
Last updated
Last updated
Instructions to if the Whatsapp phone you want to use is new or isn't already in Whatsapp API
Intructions to set up a phone number that is in another platform and is already using Whatsapp API
In the WhatsApp template section in WhatsApp manager you can create & submit template directly in WhatsApp manager, and once the template is approved, you can go to GoChat to sync the template back to GoChat.
You can also click “New Template” button in GoChat, and then you can directly create and submit template right inside of GoChat.
To see the stats and measure the effectiveness of a template campaign you can see the stats available in these buttons on the right side of the teble. These metrics are delivered by Meta directly so you will be able to see the same inside your Facebook Busines Account. Some of the metrics you will find are: delivery counts, buttons clicked, read teamplates, costs
Businesses can enable Catalogs to share products with customers using Multi and Single-Product messages or showcase their products and services to their customers in the WhatsApp App, allowing them to browse through and add items to their cart without leaving the conversation, providing a seamless and convenient shopping experience.
If you click the “Catalog” link, you will be redirect to WhatsApp Manager, and click “Catalog”, and click “Choose a Catalog”, from the drop down menu, select the catalog that you want to connect.
Click “View catalog” if you want to view or manage the catalog, Click “Connect Catalog”, and then this WABA numbers will connect to the catalog.
If you want to sync the product catalog from Facebook to GoChat native ecommerce, you can go to “Integrations”, and then go to “E-commerce” category, and then click “Facebook Business”, and login your Facebook account.
After you login your Facebook account, you will be redirect back to GoChat, and then click “List Business Catalogs” button.
Find the catalog that is linked to your WABA numbers, and click the “Facebook → Local” button, and then your catalog products will sync back to GoChat Ecommerce → Products.
If you open any products that is synced to GoChat Ecommerce → products, all the product title, description, images, prices are in sync with Facebook Catalog messages.
You will need retailID to send WhatsApp product catalog message, you can find the retailID synced to SKU in the product section.
Your business can change the display names up to 4 times in a 30-day period. Once the 30-day period is up, a new 30-day period begins and your businesses can again change the display names up to 4 times in this new 30-day period.
If you want to update your WhatsApp display name, you need to go to meta business manager, and go to WhatsApp manager
Click the blue link and Select the phone number you wish to update the display name. and then click the “Edit” icon as per screenshot below
In the Edit Display Name section, enter a new display name. Display names should have a relationship with your business and use branding consistent with external sources (e.g. your website).
Your display name will need to be approved by WhatsApp before an updated certificate becomes available. After this is approved, please re-register your number, and then your display name will be active.
You will need first to add the new phone numbers in your WhatsApp manager account from meta business manager.
Meta have phone number limitations for WhatsApp manager. If you have reached the limits, you will need to contact meta to increase the limits.
Once the new phone number is added into your WhatsApp manager account, you can go to GoChat, and click “Sync numbers”
Then you will see the new number added into GoChat.
In the settings, you will first need to “Verify the phone number” and then “Register the number”
You can click “Verify the phone number” first.
This option is only available for the new embed sign up. The old private app connection method don’t have such option.
Then you can choose SMS or Voice to verify the phone number.
You can read the migration process below from meta directly.
This is most unclear error that need further assistance. Business account creation could have failed due to various reasons.
If you got such error, please use an active Facebook account or contact Support for resolution.
==> An error occurred while processing this request. Please try again later.
You have reached the limit for the number of Businesses you can create at this time.
There is a limit to the number of Business Accounts that you can create.
==> Please use an existing Business Account or delete/close unused Business Accounts
Your Facebook account is too new to create a business account. Try again in an hour.
New Facebook accounts have to wait for some time to create a Business Manager account.
=> Please use an existing active Facebook account or wait for a few hours before using your new account. The new Facebook account can be actively used during the wait period.
We limit how often you can post, comment or do other things in a given amount of time in order to help protect the community from spam. You can try again later.
Your Facebook account was flagged because of suspicious behavior.
==> You need to use an existing, active Facebook account with no prior issues.
You're no longer allowed to use Facebook Products to advertise. You can't run ads, manage advertising assets or create new ad or business accounts.
You are unable to create new Business Manager accounts due to previous suspicious behavior.
==> Please use an existing, active Facebook account with no prior issues.
Your payment account is disabled
Your payment account was disabled due to previous suspicious behavior.
A User Can Only Create One Business User At One Time
You can only create a single Business Account within a given time period.
==> Please use an existing Business Account to onboard.
The name you chose for your business isn’t valid. Consider using xxx.
==> Please add a valid name that matches the name of your business.
User does not have permission to create WhatsApp Business Accounts.
You do not have the Admin level permission needed to create WhatsApp Accounts under the Business Account you selected.
==> Get Admin access to the Business Account to proceed or select an account you have Admin permissions for.
This WhatsApp Business Account is not available to use.
If you see this error message, and you can’t select the WhatsApp business account you want. It is because one of the reasons below:
You don’t have the permission to manage that WhatsApp business account
That WhatsApp business account already managed by private apps or other platform
The solution to this issue is to apply for the admin permission for the WhatsApp business account or disconnect the WhatsApp business account from other platforms.
You can only create a limited number WhatsApp Business Accounts before your business and WhatsApp account verification is complete. You can create additional accounts after you are verified.
You tried to create multiple WhatsApp Business Accounts under an unverified business.
==> You can create additional WhatsApp Business Accounts only when Business Verification and WhatsApp account checks are complete. Start Business Verification for the account by visiting Business Manager.
We can't verify the Facebook Business Account that you selected. Go back to the previous screen to select a different account, or go to Facebook Business Manager for support.
The Facebook Business Account selected doesn't comply by our policies to use WhatsApp Business API and couldn't be verified.
==> Visit your Business Manager account to get more information about this Facebook Business Account. If your Business Verification submission is rejected, you should have received an email notification with the detailed reasons. You could try resubmitting your Business Verification if you think this was an error or create a WhatsApp Business Account using a Facebook Business Account that has already been verified.
Something has gone wrong. You will need to contact support and try again.
This could be an intermittent issue on WhatsApp.
==> You can retry the flow in a few minutes.
You have already linked the maximum number of phone numbers allowed for this business account. Delete a phone number to continue or request additional numbers.
By default, meta only allow maximum 2 phone numbers to one WhatsApp business account, if you need more numbers, you need to reach out to meta support to increase the allowed number limits.
According to meta policies: “Business portfolios are initially limited to 2 registered business phone numbers, but this limit can be increased to up to 20.
This phone number already exists in your list of phone numbers.
You are trying to add a phone number that already exists in your WhatsApp Business Account.
==> Go back into the flow or restart the flow to select the existing phone number.
This number is registered to an existing WhatsApp account. To use this number, disconnect it from the existing account. Then, return to this page and re-enter the number. Note: It may take up to 3 minutes for the number to become available.
The phone number was already registered on our platform (i.e., WhatsApp Messenger, WhatsApp Business App or Whatsapp Business API).
==> Go to “WhatsApp Cloud” settings, and De-register the number if you want to use it. or register a new number.
Your verified name violates WhatsApp guidelines. Please edit your verified name and try again.
The name used for the phone number's business profile does not meet our guidelines.
Something has gone wrong. You will need to contact support and try again.
There was a problem in creating the phone number's Business Profile.
==> Re-enter the correct Business Profile name according to the guidelines and other details.
Phone number ownership is already verified.
==> This phone number has already been verified. You can try refresh the page to see the change applied.
Your phone number doesn't appear to be valid. Please double check it, or try again after 5 minutes.
An incorrect phone number was entered or we do not support numbers of this format.
==> Make sure the number is operational and verified by a telecom provider. We do not currently support Interactive Voice Response (IVR) numbers.
You have guessed too many times.
To block spam, the system only allows a limited number of verification attempts.
==> You have to wait for about 12 hours before retrying. After this waiting period, come back to the flow and select existing accounts and phone numbers to verify again.
There was an error verifying this phone number. Please try again later.
There was a problem with the verification code.
==> Please retry again later.
You have requested your code too many times.
To block spam, the system only allows a limited number of verification tries.
==> We limit the number or times you can request a code within a certain time frame. Come back to the flow after the specified time and select existing accounts and phone numbers to request a code again.
You might see the error message below:
[{"code":131053,"title":"Media upload error","message":"Media upload error","error_data":{"details":"Sticker file could not be processed. Please choose a different file."}}]
The reason is:
This might be the url you are using in the message or template message isn’t publicly available to access.
Also, this can be the file format you are using are not supported by WhatsApp.
Solution:
You can check the URL you are using, and make sure the file url starts with https, and ends with the file format at the end of URL, and also this media file should be always publicly accessible.
If you see this error message, this message can be triggered if you are trying to use “WhatsApp Flow” feature, you will need to check if your meta business manager is verified or not.
For certain feature like WhatsApp Flow, meta requires verified business manager to get access.
The request included one or more unsupported or misspelled parameters.
You might see error message like this:
Error sending payload: 2018047 (#100) อัพโหลดไฟล์แนบไม่สำเร็จ
Error sending payload: 2018062 (#100) O URL fornecido não está na lista de liberação de extensões do Messenger
It’s possible that you are using a few user custom field variables, but some of the variables don’t have the value populated.
You can add a conditional check about all the variables you are about to use, and notify the admin if there are any errors.
You can also go to the error logs, and locate the user, and check the value of the variable used in the message, and confirm if all of them have the correct value.
You might see the error message like this:
[{"code":131048,"title":"Message failed to send because there are restrictions on how many messages can be sent from this phone number.This may be because too many previous messages were blocked or flagged as spam.","href":"https:\/\/developers.facebook.com\/docs\/whatsapp\/cloud-api\/support\/error-codes\/"}]
This may be because too many previous messages were blocked or flagged as spam
It’s because you have sent many messages to other users, but many messages were blocked or flagged as spam.
So meta has placed some limitations on your number. You need to maintain a healthy account quality, otherwise, your account or WABA number might get blocked.
You might see the error message like this:
The reason is that you don’t have enough funds to your 360dialog account, you will need to purchase more credit from 360dialog. please go to your 360dialog account, insights & billings and add more credits.
If you see this error, the reason is: Permission is either not granted or has been removed.
When you connect your WhatsApp account, you need to select all the permission required.
Bot Not Responding Initially: This indicates a connection issue. The video recommends referring to their "WhatsApp Cloud API not working" video for solutions, covering four main checkpoints.
Bot Stops Responding After Initial Functionality: This issue primarily stems from token expiration, which typically happens after 59-60 days. The solution involves refreshing the token by clicking the "refresh token" button upon logging in.
Other causes include:
Facebook Password Change: Check error logs for "Invalid Session Token." Reconnecting the WhatsApp Cloud API should resolve this.
Workspace Owner Notification: The owner receives an email 7 days before token expiry.
"99% of the issue is the token expired...If the token expired your Bot will not responding."
Issues with Template Messages: While other bot functions work correctly, template messages pose problems like:
Failure to sync template messages back to YoGoChat
Inability to submit template messages within YoGoChat
Encountering "200 permission error" when submitting WhatsApp template messages in YoGoChat
Ensuring sufficient permissions is critical to resolving template message issues. Three areas require attention:
App Permissions: Go to the specific app created for the Cloud API in your Facebook developer account. Under configurations, ensure "web hook fields" have all necessary permissions enabled, including sending messages and receiving various data points.
Business Integration Settings:
Disconnect and reconnect your Cloud API account.
Click "Business Integration Settings" in the popup window.
Grant necessary permissions to the relevant apps (YoGoChat app for partners, Uat app for customers). This includes permissions for managing WhatsApp accounts, Facebook Business Manager accounts, Instagram accounts, and more.
99% of the permission issues with your WhatsApp template message for the Cloud API is because we do not have the account access for your WhatsApp business account or for your Facebook business manager account.
Private App Permissions in Facebook Developer Account:
Verify and edit permissions for the private apps created for WhatsApp Business account management.
Ensure the correct account is selected, granting permissions to manage conversations and access the WhatsApp Business manager account.
Summary: The video emphasizes that most WhatsApp Cloud API issues relate to token expiration or insufficient permissions. Carefully checking and updating permissions in the designated areas should resolve most template message problems.
So when we call meta API to send the message through their API, it takes longer then 10 seconds. That’s the default timeout settings from meta.
In this scenerio, it might be meta server is slow to respond or GoChat server is having issues. You can check meta API status page first, if there isn’t any outage, reach out to GoChat support.
You might see the error code:
(#131008) Required parameter is missing Parameter of type text is missing text value
Reason:
The request is missing a required parameter.
Solution:
It’s possible that you are using a few user custom field variables, but some of the variables don’t have the value populated.
You can add a conditional check about all the variables you are about to use, and notify the admin if there are any errors.
You can also go to the error logs, and locate the user, and check the value of the variable used in the message, and confirm if all of them have the correct value.
This means that you have used a WhatsApp template message, but we can’t find this template message from your WhatsApp account.
This might be the user changing the message template or deleted it from the WhatsApp business manager and the changes have not been synced back into the GoChat Chatbot
It looks like your whatsapp business account has been locked by meta. you need to contact meta to get support.
Also, you can go to your WhatsApp manager in the meta business manager for any notifications related to this error.
You might see the error message like this:
[{"code":130472,"title":"Failed to send message because this user's phone number is part of an experiment","href":"https:\/\/developers.facebook.com\/docs\/whatsapp\/cloud-api\/support\/error-codes\/"}]
You might see the error message like this:
[{"code":131047,"title":"Re-engagement message","message":"Re-engagement message","error_data":{"details":"Message failed to send because more than 24 hours have passed since the customer last replied to this number."},"href":"https:\/\/developers.facebook.com\/docs\/whatsapp\/cloud-api\/support\/error-codes\/"}]
[{"code":470,"href":"https:\/\/developers.facebook.com\/docs\/whatsapp\/api\/errors\/","title":"Message failed to send because more than 24 hours have passed since the customer last replied to this number"}]
This is because it has been more than 24 hours since you last received a user initiated message - the session is closed and you can no longer use free-form messages. Please find a way to restrict message sending if there was no incoming message for the given user/phone number within 24h. Alternatively, you can contact the user using a Template Message.
You might see the error like this:
(#131056) (Business Account, Consumer Account) pair rate limit hit
The reason for this error:
Too many messages sent from the sender phone number to the same recipient phone number in a short period of time.
Solution:
Wait and retry the operation, if you intend to send messages to the same phone number. You can still send messages to a different phone number without waiting
Learn more information here:
You might see the error message like this:
Error validating access token: The session has been invalidated because the user changed their password or Facebook has changed the session for security reasons.
Users who connected to WhatsApp have changed their password on their Facebook account. As a security measure Meta logs out all third-party platforms so reconnect once to establish the connection again will resolve the issue
The solution is to reconnect the channel. Because the user might have changed their password, so the previous token is not valid anymore.
You might see the error like this:
[{"code":131048,"title":"Spam Rate limit hit","message":"Spam Rate limit hit","error_data":{"details":"Message failed to send because there are restrictions on how many messages can be sent from this phone number.This may be because too many previous messages were blocked or flagged as spam."},"href":"https:\/\/developers.facebook.com\/docs\/whatsapp\/cloud-api\/support\/error-codes\/"}]
Reason:
Message failed to send because there are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.
Solution:
You will usually see the error message like this:
[{"code":131026,"title":"Receiver is incapable of receiving this message","message":"Receiver is incapable of receiving this message","error_data":{"details":"Message Undeliverable."}}]
Possible reasons:
Unable to deliver a message. Reasons can include:
· The recipient phone number is not a WhatsApp phone number.
· Recipient has not accepted our new Terms of Service and Privacy Policy.
· Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:
o Android: 2.21.15.15
o SMBA: 2.21.15.15
o iOS: 2.21.170.4
o SMBI: 2.21.170.4
o KaiOS: 2.2130.10
o Web: 2.2132.6
Solution:
Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp.
Learn more information:
This error is because the user doesn't give enough permission. Reference video below to solve the issue:
Bot Not Responding (Initial Connection)
Problem: After setup, the bot fails to respond to initial messages.
Solution: Likely a connection issue. Verify the four key setup points as detailed in a separate Youat channel video.
Bot Stops Responding After Initial Setup
Problem: The bot works initially but stops responding later.
Solution:
Refresh the token to extend validity by 60 days. Workspace owners get notified 7 days before expiry.
If a Facebook password change caused an "invalid session token" error, reconnect the WhatsApp Cloud account.
Issues with Template Messages
Problem:
Trouble syncing or submitting template messages in GoChat.
"200 permission error" when submitting WhatsApp template messages.
Solution: Verify permissions in these areas:
WhatsApp App Configurations: Ensure proper webhook and app permissions.
Facebook Business Integration: Check and reconnect Cloud API, ensuring "View and Edit" permissions for related accounts and apps.
Private App Permissions: Confirm private apps in Facebook Developer have necessary permissions.
Granting appropriate permissions in Facebook Business Manager, WhatsApp Business Manager, and associated private apps is essential for resolving template message issues and ensuring bot functionality.
This limit applies to meta channels(Messenger, Instagram, WhatsApp). If the user hasn't engaged with your bot for the past 24 hours.
You can’t reach them directly. For WhatsApp, you will need to send a template message, for Messenger, you will need to send recurring notification or one time notification.
There aren't any good options to reach the Instagram user if they are outside of a 24 hour window.
The error code 131026, Message undeliverable
Possible reasons:
Unable to deliver a message. Reasons can include:
· The recipient phone number is not a WhatsApp phone number.
· Recipient has not accepted our new Terms of Service and Privacy Policy.
· Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:
o Android: 2.21.15.15
o SMBA: 2.21.15.15
o iOS: 2.21.170.4
o SMBI: 2.21.170.4
o KaiOS: 2.2130.10
o Web: 2.2132.6
Solution:
Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp.
Learn more information:
Unable to deliver a message. Reasons can include:
· The recipient phone number is not a WhatsApp phone number.
· Recipient has not accepted the new Terms of Service and Privacy Policy.
· Recipient using an old WhatsApp version; must use the following WhatsApp version or greater:
Confirm with the recipient that they agree to be contacted by you over WhatsApp and are using the latest version of WhatsApp.
The full error can be something looks like this:
[{"code":131042,"title":"Message failed to send because there were one or more errors related to your payment method.","href":"https:\/\/developers.facebook.com\/docs\/whatsapp\/cloud-api\/support\/error-codes\/"}]
This error usually happens in Cloud API, WhatsApp channel.
You will need to go to your Facebook business manager, and then WhatsApp manager, and then check if you have any payment issues with your billing. Because meta charge for the WhatApp template message, so you will need to set up the valid credit card in the billing section in your WhatsApp manager.
You might see the error message like this:
(#100) Unexpected key "index" on param "template['components'][0]['parameters'][0]".
Reason:
The request included one or more unsupported or misspelled parameters.
Solution:
This error means the template don’t exist The template does not exist in the specified language or the template has not been approved.
This error arises when a 3rd party storage (Cloudinary, S3 etc) is integrated and a file is shared using a flow without the required permissions resulting in files of certain formats not being delivered to users.
To resolve this, either disconnect your storage integration or enable the settings that allow us to share the files.
Below is an example from cloudinary;
Check meta offical common errors .
==> Please contact Facebook to assist at
If your business has been , or if you open 1,000 or more in a 30-day moving period using templates with a high , we will determine if your API usage warrants a phone number limit increase.”
Learn more about the .
We were unable to upload the media for one or more reasons, such as an . Refer to the error.error_data.details value for more information about why we were unable to upload the media.
Learn more information here:
The message could not be sent. You do not have enough funds on your conversation prepaid balance to engage in any paid conversation. Please proceed to -> 'Insights & Billing' in order to top up your balance and optionally enable auto-renewal, which will prevent you from running out of funds in the future.
Meta API status page:
Learn more information here:
Message was not sent as part of an . See .
Learn more here:
Check your quality status in the WhatsApp Manager and see the documentation for more information.
More information here:
See the endpoint's to determine which parameters are supported and how they are spelled.
Ensure when setting the business public key, it is a .
Ensure there is no mismatch between the phone number id you are and a previously stored phone number id.
Make sure your template has been approved and the template name and language locale are correct. Please ensure you follow .
