FAQ & Common Errors for WhatsApp bot

Encountering errors while using WhatsApp channels can disrupt your communication flow and hinder business operations. Understanding these common issues and their solutions can help you maintain seamless interactions and improve your service reliability.

WhatsApp Channel Common Errors

Error: "Media Upload Error"

You may encounter the following error message:

[{"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 cause is:

The URL used in your message or template might not be publicly accessible.

Additionally, the file format you're using might not be supported by WhatsApp.

Solution:

We couldn't upload the media due to reasons like an unsupported media type (). Refer to error.error_data.details for more details on the upload failure.

Ensure the URL you are using starts with https, ends with the correct file format, and is always publicly accessible.

Blocked by Integrity: Integrity Requirements Not Met

If you encounter this error, it may occur when using the "WhatsApp Flow" feature. Check if your Meta Business Manager is verified.

For features like WhatsApp Flow, Meta requires a verified Business Manager for access.

Error: "Sending Payload: (tel:) (#100)"

This error occurs when the request contains unsupported or misspelled parameters.

You might encounter error messages such as:

Error sending payload: (tel:) (#100) อัพโหลดไฟล์แนบไม่สำเร็จ

Error sending payload: (tel:) (#100) O URL fornecido não está na lista de liberação de extensões do Messenger

You might be using user custom field variables, but some variables may not have values populated.

Add a conditional check for all variables you plan to use and notify the admin if errors occur.

Check the error logs, find the user, verify the variable values in the message, and ensure they are correct.

Learn more here:

Error: "Message Failed to Send Due to Restrictions on Message Volume"

You may see an 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 due to excessive previous messages being blocked or flagged as spam.

This occurs because many of your messages were blocked or flagged as spam.

Meta has imposed limitations on your number. Maintain a healthy account quality to avoid your account or WABA number being blocked.

Error: "Insufficient Funds on Conversation Prepaid Balance"

You may see an error message like this:

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' to top up your balance and optionally enable auto-renewal to prevent running out of funds in the future.

This error indicates insufficient funds in your 360dialog account. Purchase more credits by visiting your 360dialog account, navigating to insights & billings, and adding credits.

Error: "(#200) Permissions Error"

If you encounter this error, it means permission has not been granted or has been removed.

When connecting your WhatsApp account, ensure you select all required permissions. Here is a video for detailed guidance:

When you connect your WhatsApp account, you need to select all the permission required. Here is a video to explain in details:

This error occurs when the Meta API takes longer than 10 seconds to send a message, which is the default timeout setting from Meta.

In this situation, the Meta server might be slow to respond, or there could be issues with the Flexito OmniAI server. Check the Meta API status page first; if no outage is reported, contact Flexito OmniAI support.

Meta API status page:

Error: "Required Parameter is Missing - Error Code 131008"

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:

You might be using user custom field variables, but some variables may not have values populated.

Add a conditional check for all variables you plan to use and notify the admin if errors occur.

Check the error logs, find the user, verify the variable values in the message, and ensure they are correct.

Learn more here:

Error: "WhatsApp Message Template Not Found"

This error indicates that the WhatsApp template message you used cannot be found in your WhatsApp account.

This may occur if a user changes or deletes the message template from the WhatsApp Business Manager, and the changes have not synced back to the Flexito OmniAI Chatbot.

Error: "Business Account Has Been Locked"

It seems your WhatsApp business account has been locked by Meta. Contact Meta for support.

Additionally, check your WhatsApp Manager in the Meta Business Manager for any notifications related to this error.

Error: "Failed to Send Message Because This User's Phone Number is Part of an Experiment"

You may see an 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\/"}] The message was not sent as part of an experiment. See Marketing Message Experiment for more details.

Learn more here:

Error: "Message Failed to Send Because More Than 24 Hours Have Passed Since the Customer Last Replied"

You may see an 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 occurs because it has been over 24 hours since you received a user-initiated message, closing the session and preventing free-form messages. Restrict message sending if no incoming message is received within 24 hours. Alternatively, use a Template Message to contact the user.

Error: "Business Account and Consumer Account Pair Rate Limit Hit"

You may see the error like this:

(#131056) (Business Account, Consumer Account) pair rate limit hit

Reason for this error:

Too many messages have been sent from the sender phone number to the same recipient phone number in a short 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 here:

Error: "Error Validating Access Token"

You may see an 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. Reconnect once to establish the connection again and resolve the issue.

The solution is to reconnect the channel. The user might have changed their password, rendering the previous token invalid.

Error: "Spam Rate Limit Hit"

You may 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:

Check your quality status in the WhatsApp Manager and see the Quality-Based Rate Limits documentation for more information.

Error: "Receiver is Incapable of Receiving This Message"

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:

o SMBA:

o iOS:

o SMBI:

o KaiOS:

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 here:

Error: "#200 Permission Error - WhatsApp Cloud API"

This error occurs because the user hasn't granted enough permissions. Refer to the video below to resolve the issue:

This error is because the user doesn't give enough permission. Reference video below to solve the issue:

This limit applies to Meta channels (Messenger, Instagram, WhatsApp). If the user hasn't interacted with your bot for the past 24 hours.

You can't reach them directly. For WhatsApp, send a template message; for Messenger, send a recurring or one-time notification.

There are no effective options to reach Instagram users outside the 24-hour window.

More information here:

Error: "Message Undeliverable"

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:

o SMBA:

o iOS:

o SMBI:

o KaiOS:

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 here:

Error: "Message Undeliverable - Code 131026"

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.

Error: "Business Eligibility Payment Issue"

The full error may look 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 occurs in the Cloud API, WhatsApp channel.

Check your Facebook Business Manager, then WhatsApp Manager, for any payment issues in your billing. Since Meta charges for WhatsApp template messages, ensure you have a valid credit card set up in the WhatsApp Manager billing section.

Error: "Invalid Parameter #100"

You may see an 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:

Refer to the endpoint's reference to determine supported parameters and their correct spelling.

Ensure the business public key is a valid 2048-bit RSA public key in PEM format.

Ensure there is no mismatch between the phone number ID you are registering and a previously stored phone number ID.

Error: "(#132001) Template Name Does Not Exist in the Translation"

This error indicates the template does not exist in the specified language or has not been approved.

Ensure your template is approved and the template name and language locale are correct. Follow the message template guidelines.

Error: "(#131053) Downloading Media from Weblink Failed with HTTPS Code 401, Unauthorized"

This error occurs when a third-party storage (Cloudinary, S3, etc.) is integrated and a file is shared using a flow without the required permissions, resulting in certain file formats not being delivered to users.

To resolve this, either disconnect your storage integration or enable the settings that allow file sharing.

Below is an example from Cloudinary:

Below is an example from cloudinary;

This error occurs when a number is ported/migrated from a service provider to Cloud API or vice versa while connecting to the same bot. You will encounter this error when trying to register the number using WhatsApp embed signup.

To resolve this, pause and resume the current bot, then try again.

Issues Connecting WhatsApp Cloud API Number to Facebook Ads for Message Delivery

This issue arises when users directly add their WhatsApp number inside the Ads Manager. When this happens, Facebook offers the option to connect the number with the WhatsApp Business App, causing a conflict because the number is already registered with the WhatsApp Cloud API. Consequently, the number fails to connect properly for ad delivery.

Issues in connecting their WhatsApp Cloud API number to Facebook Ads for message delivery

Follow these steps to connect a Cloud API WhatsApp number to Facebook Ads: Log in to Facebook and switch to your Page profile. Link the WhatsApp number registered with the Cloud API to your Page. Once linked, go to Ads Manager. Select this WhatsApp number when setting up your campaign for message delivery.

Follow these steps to connect Cloud API WhatsApp number to Facebook Ads: Log in to Facebook and switch to your Page profile. Link the WhatsApp number that is registered with the Cloud API to your Page. Once linked, go to Ads Manager. Now select this WhatsApp number when setting up your campaign for message delivery.