WhatsApp Business Integration
with Amazon Connect

No SendIntegrationEvent in CloudTrail

If SendIntegrationEvent never fires, Social Messaging either isn't receiving the message from Meta, or can't resolve the phone number. Work through these in order:

ResourceNotFoundException: "Origination phone number id not found"

This error from GetLinkedWhatsAppBusinessAccountPhoneNumber means Connect holds a phone-number-id that no longer exists in Social Messaging. The number shows "Active, WhatsApp" in Connect but points at a ghost record.

Most likely causes:

• The phone number was removed and re-added on the Social side after Connect imported it — the phone-number-id changed but Connect still holds the old one.
• Cross-account drift — the IAM role belongs to an account where the phone number ID doesn't exist.
• You have two WABAs; the event destination was set on WABA A but the number being tested belongs to WABA B.

Diagnosis:

# What Social actually knows
aws socialmessaging list-linked-whatsapp-business-accounts --region <region>
aws socialmessaging get-linked-whatsapp-business-account \
  --id <waba-id> --region <region>
# Note phoneNumbers[].phoneNumberId

# What Connect holds
aws connect list-phone-numbers-v2 \
  --instance-id <connect-instance-id> --region <region>
# Check SourcePhoneNumberArn — phone-number-id is embedded

Fix: Release the number from Connect, then re-save the event destination in the Social console to re-trigger ImportPhoneNumber with the current ID. Re-attach the contact flow.

DependencyException: "Error while communicating with Meta"

AssociateWhatsAppBusinessAccount has two phases. Phase 1 (OAuth handshake) almost always succeeds. Phase 2 (setupFinalization) fails with a 502 from Meta for several reasons:

• Using a Meta-generated virtual number — Meta does not support connecting their virtual numbers to third-party Cloud API providers. Switch to Add a new number and provide a real phone number.
• WABA in a bad state from prior restriction or billing history — repeated failed attempts make this worse. Stop retrying and open an AWS Support ticket with the RequestID from the most recent DependencyException.
• Rate limiting — more than ~40 AssociateWhatsAppBusinessAccount calls in a day triggers Meta's abuse detection. Stop all attempts and wait before retrying.

Messages not arriving despite everything looking correct

If the WABA is COMPLETE, the event destination is enabled, and the phone number is imported — but SendIntegrationEvent never fires — check for a Condition block in the IAM role's trust policy.

A condition that looks valid (e.g., aws:SourceAccount) can silently block sts:AssumeRole calls from social-messaging.amazonaws.com. The trust policy should be exactly:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "Service": "social-messaging.amazonaws.com" },
    "Action": "sts:AssumeRole"
  }]
}

No conditions. If you added any, remove them and wait a few minutes for the policy to propagate.

WABA is Account Restricted

A restricted WABA blocks all three things needed for the integration: initiating conversations, responding to messages, and adding phone numbers. This is a Meta enforcement action — no AWS config change can unblock it.

Immediate restriction at account creation (with zero activity) is caused by the Business Portfolio's trust score, not a policy violation. Common triggers:

• The Business Portfolio has prior enforcement history from any associated asset (ad accounts, pages, apps)
• The admin's personal Facebook account is new, thin, or previously flagged
• The selected business category falls into a high-risk group (finance, healthcare, legal, real estate)
• No Business Verification, no verified domain, no ad spend history on the Portfolio
• Account created from an IP Meta associates with fraud or VPN traffic

What to do:

1. Check Meta Business Manager → Account quality — if there is a "Request Review" button, submit an appeal with business documentation. This works even for "permanent" restrictions.
2. Complete Business Verification: Meta Business Manager → Business Settings → Security Center → Start Verification.
3. Verify your domain under Brand Safety → Domains.
4. If the Portfolio itself is irrecoverable, create a new one under a clean, established Facebook admin account. A new WABA under a flagged Portfolio will be immediately restricted again.

Billing currency error: "WABA was previously billed in a currency other than USD"

AWS End User Messaging Social invoices in USD and pays Meta. Meta only allows a WABA's billing currency to be set once. If this WABA previously had messages billed in a non-USD currency through any provider, the currency is locked and AWS cannot assume billing.

There is no fix — Meta does not expose a "change billing currency" operation. Options:

• Create a brand new WABA under the same Business Portfolio, do not send any messages through another platform first, then link it to AWS. A fresh WABA will have its currency set to USD when AWS links it.
• Move the phone number to the new WABA in Meta Business Manager before linking to AWS, so customers keep the same number. Meta requires the number to be unregistered from the old WABA first.

400 error: "Value at roleArn failed to satisfy constraint"

This 400 validation error occurs when the service-linked role AWSServiceRoleForSocialMessaging is passed as the event destination role ARN. Service-linked roles have a multi-segment path (role/aws-service-role/...) that fails the API regex, which requires a single-segment path.

The two roles serve completely different purposes:

• AWSServiceRoleForSocialMessaging — auto-created by AWS for its own internal operations (WABA linking, Meta sign-up plumbing). You cannot and should not use it as a delivery role.
• Event destination role — a customer-managed role you create (Step 2 above) that Social Messaging assumes to call connect:SendIntegrationEvent.

Fix: If you haven't already, create the customer-managed role from Step 2 and switch to Enter IAM role ARN in the console instead of using the dropdown.

Display name changed — number needs to be re-registered

After a WABA display name change is approved by Meta, you may see the following message in the AWS End User Messaging Social console or WhatsApp Manager:

Re-importing the phone number alone is not sufficient. Meta requires the phone number to be fully re-registered under the new display name, which means a complete unlink and re-link cycle through the embedded sign-up flow.

1. In the AWS End User Messaging Social console, disassociate (unlink) the WABA.
2. Click Link WABA and go through the embedded sign-up flow again. Pay close attention to select the exact same Business Profile, same WABA name, and the registered phone number — do not create new resources or choose a different number.
3. Once the WABA is re-linked, release the phone number from Amazon Connect.
4. Re-import the phone number using import-phone-number (see Step 6 above).
5. Re-attach the contact flow to the newly imported number.

Once the import completes successfully, the updated display name will be reflected in both WhatsApp Manager and the AWS End User Messaging Social console.

ImportPhoneNumber fails: phone number quota exceeded

Amazon Connect enforces a default limit of 5 phone numbers per instance.⁷ When this limit is reached, ImportPhoneNumber will fail. This typically affects numbers that are not already present in your Connect phone number list, or numbers listed as Display Only. If the WhatsApp number already appears in your Connect phone number list (for example, previously claimed as a voice DID), releasing it first and then re-importing it as a WhatsApp channel works fine — releasing frees the slot before the import reclaims it. You may also see this error the very first time you claim a number if the instance has a pre-existing restriction, in which case only AWS Support can resolve it.

How to check your current usage:

aws connect list-phone-numbers-v2 \
  --instance-id <connect-instance-id> \
  --region <region> \
  --query 'length(ListPhoneNumbersSummaryList)' \
  --output text

Options to resolve:

• Release an unused number — if you have numbers in Connect that are no longer in use, release one to free up the slot:
  aws connect release-phone-number --phone-number-id <id> --region <region>
• Request a quota increase — open the Service Quotas console or use the AWS CLI to request a higher limit for your Connect instance.⁸ This is a resource-level quota, so the increase applies to the specific instance ARN:

# Find the quota code for "Phone numbers per instance"
aws service-quotas list-service-quotas \
  --service-code connect \
  --region <region> \
  --query 'Quotas[?contains(QuotaName, `Phone number`)].[QuotaName,QuotaCode,Value]' \
  --output table

# Request an increase (replace quota-code and desired-value)
aws service-quotas request-service-quota-increase \
  --service-code connect \
  --quota-code <quota-code> \
  --desired-value 10 \
  --region <region>