Setting the file. One moment.
Skill 82 · AWS Social Messaging
Subchapter 82.5
references/troubleshooting-delivery.mdMarkdown4 KBView on GitHub
Security: See SKILL.md — Security Considerations for encryption, IAM, and audit logging guidance.
aws socialmessaging get-linked-whatsapp-business-account --id "waba-XXXXXXXXXXXXXXXXXXXX"
COMPLETEqualityRating — LOW restricts sending capacityaws socialmessaging get-linked-whatsapp-business-account-phone-number \
--id "phone-number-id-XXXXXXXXXXXXXXXXXXXX"
aws socialmessaging list-whatsapp-message-templates --id "waba-XXXXXXXXXXXXXXXXXXXX"
Look for:
REJECTED templates — recreate with compliant contentPENDING > 24h — create a new templateaws sns list-subscriptions-by-topic \
--topic-arn "arn:aws:sns:us-east-1:123456789012:whatsapp-events"
Confirmedaws service-quotas get-service-quota \
--service-code social-messaging \
--quota-code L-XXXXXXXX
Review service quotas (opens in a new tab) for quota codes and defaults. New WABAs have lower limits that increase with quality rating.
aws cloudtrail lookup-events \
--lookup-attributes AttributeKey=EventSource,AttributeValue=social-messaging.amazonaws.com \
--max-results 20
CloudTrail records all social-messaging API calls. Look for SendWhatsAppMessage events with error details not visible in the CLI response. Verify CloudTrail is enabled for the account/region. Ensure CloudTrail logs are encrypted with a KMS CMK (see SKILL.md — Security Considerations).
| Symptom | Cause | Fix |
|---|---|---|
| Send returns error | Invalid --origination-phone-number-id | Use the ID (phone-number-id-XXXX), not the phone number |
| Send returns error | Invalid recipient format | Must be E.164 with + prefix (e.g., +14155551234) |
| Send succeeds but not delivered | Recipient not on WhatsApp | Messages silently dropped; no fix |
| Send succeeds but not delivered | 24h window expired (freeform) | Use template message instead |
| Send succeeds but not delivered | Rate limited | Check quotas; quality rating must improve |
| Template REJECTED | Non-compliant content | Recreate with correct category-matching language |
| Template reclassified | Ambiguous body text | Delete, recreate with clearly transactional language |
| No delivery callbacks | Event destination missing | Configure via put-whatsapp-business-account-event-destinations |
| No delivery callbacks | SNS subscription pending | Confirm the subscription endpoint |
Common codes — see Meta’s error reference (opens in a new tab) for the full list.
| Code | Meaning |
|---|---|
| 131026 | Recipient phone number not on WhatsApp. Verify E.164 format with + prefix, confirm number has active WhatsApp, retry after a brief delay for transient failures, and check if your phone number quality rating has degraded |
| 131049 | Message failed — requires recent user engagement (marketing templates) |
| 131047 | Re-engagement message — more than 24h since last reply |
| 131051 | Unsupported message type |
| 130472 | Number deregistered from WhatsApp |