This error appears when the phone number was previously used with another WhatsApp Business API provider or with the WhatsApp mobile/business app. If the number was used in the standard WhatsApp app, you must disconnect it before connecting it to Intercom.

If used with another API provider:
Follow the onboarding flow for migrating an existing WhatsApp phone number, and exit the embedded onboarding after Step 2.

If used with a mobile WhatsApp app:
Follow the steps under the Learn more link shown in the error to disconnect the number from that WhatsApp account, then you should be able to retry our onboarding process successfully.

If neither applies, contact Support with your:

We can attempt a manual connection.

Check your browser console for additional detail.

If this occurred during migration:
The migration may already have succeeded. Try using the “I’m integrating WhatsApp for the first time” flow and select the newly created accounts.

If you are unable to save your business profile settings and are receiving a 500 error back in your browser console, it's likely a validation error returned to us by WhatsApp on the profile setting you are trying to update. There are some details on the restrictions such as maximum number of characters here.

Check:

If both checks fail: Sending Support a screenshot of the verified number in Business Manager helps speed up resolution.

Provide Support with your:

Contact Intercom customer support for help with this error.

Ensure your WhatsApp number is connected on the installation page.

Verify the phone number is fully approved in Meta.

This typically occurs due to restricted or disallowed words in the title or description fields.

This often occurs for numbers provisioned by third-party providers. Try the migration onboarding steps again. If unsuccessful, contact Intercom Support.

This error must be resolved by Meta Support and cannot be fixed within Intercom.

When you try to connect a number, make sure the code which is shown to you is a WhatsApp account ID.

This is usually flagged by Meta due to any phone migration error. Check the Meta docs for more details.

Additionally, if you encounter the following error: Type: OAuthException Code: 1 Error_subcode: 23881 Message: Invalid parameter Error_user_title: Cannot Create Certificate Error_user_msg: Your business doesn’t meet WhatsApp’s policy requirements. If you believe your business qualifies, reach out to Meta Business Suite Support. Official documentation can be found here.

If you encounter an error message like "(#1) Parameter Error" while connecting your WhatsApp number: Take a screenshot of the error message. Often, resolving this requires Meta support. Confirm that all settings in Meta and Intercom are configured correctly before reaching out.

Examples:

These errors indicate your business may not meet WhatsApp’s policy standards. If you believe your business qualifies, reach out to Meta Business Suite Support. Official documentation can be found here.

Take a screenshot and check your settings. Most parameter errors originate from Meta’s side and must be resolved via Meta Support.

Follow these steps:

Note: Closing the popup at the correct moment is essential to avoid this error. This is the window that you should close 👇

Check:

Intercom requires templates to use numerical placeholders (e.g., ##{{1}}) rather than descriptive ones like ##{{sf_full_name}}. Example: Hi ##{{1}}, your order ##{{2}} has been shipped.

If your templates using variables like ##{{sf_full_name}} fail, edit your template in Meta to replace descriptive placeholders with numerical ones and map these in Intercom. This ensures compatibility between WhatsApp and Intercom by mapping variables directly to Intercom attributes.

To ensure templates remain non-marketing:

WhatsApp couldn’t deliver this message because the recipient’s WhatsApp account isn’t currently able to receive messages. This can happen if the phone number isn’t registered with WhatsApp, if the recipient hasn’t accepted WhatsApp’s latest Terms of Service or Privacy Policy, or if they’re using an outdated version of the WhatsApp app (minimum required versions include Android/SMBA 2.21.15.15, iOS/SMBI 2.21.170.4, KaiOS 2.2130.10, and Web 2.2132.6).

To resolve the issue, ask the recipient via another communication channel (such as SMS, email, or phone) to confirm they can send a message to your WhatsApp Business number, accept any pending Terms of Service prompts by going to Settings > Help or Settings > Application information, and update their WhatsApp client to the latest version.

Once they complete these steps, WhatsApp should be able to deliver your messages successfully.

This message was not delivered because WhatsApp blocked it to maintain healthy ecosystem engagement, which usually means the recipient has reached a limit on how many marketing template messages they can receive within a certain period.

If you suspect this is the cause, the best action is to wait at least 24 hours before attempting to resend the template message. Sending it again sooner will likely result in the same error, as the limit can remain active for varying lengths of time.

This message was not sent as part of an experiment. For more details on experiments, see WhatsApp’s Marketing Message Experiment documentation.

This message couldn’t be delivered because WhatsApp was unable to upload the media included in it, which typically occurs when the file uses an unsupported format or doesn’t meet WhatsApp’s media requirements.

To resolve this, review the media file you’re trying to send and confirm that its format and size are supported by WhatsApp. Once the media meets WhatsApp’s requirements, you should be able to resend the message successfully.

This message couldn’t be delivered because more than 24 hours have passed since the recipient last replied to your WhatsApp number, and WhatsApp only allows free-form messages within that active 24-hour conversation window. This error can also occur if the recipient’s phone number changed during the conversation, which effectively resets the session.

To continue messaging, you’ll need to send a WhatsApp-approved template message instead. Once the recipient replies, the 24-hour window will reopen and regular free-form messages can be sent again.

This message couldn’t be delivered because the WhatsApp Business Account connected to your app has been restricted or disabled. This typically happens when WhatsApp detects a violation of their platform policies, or when details in the request can’t be verified against the account’s configuration—for example, an incorrect two-step verification PIN.

To resolve this, review WhatsApp’s Policy Enforcement guidelines to understand the type of violation and the steps required to restore the account. You can also check the WhatsApp Health Status API for more specific insight into why the account was locked or restricted. Once the underlying issue is addressed, message delivery should resume normally.