Troubleshooting WhatsApp Message Delivery
Security: See SKILL.md — Security Considerations for encryption, IAM, and audit logging guidance.
Diagnostic Flow
Step 1: Check WABA Status
aws socialmessaging get-linked-whatsapp-business-account --id "waba-XXXXXXXXXXXXXXXXXXXX"
- Registration status MUST be
COMPLETE - Check
qualityRating— LOW restricts sending capacity - If not COMPLETE, finish registration in the AWS Console (cannot be done via CLI)
Step 2: Check Phone Number Health
aws socialmessaging get-linked-whatsapp-business-account-phone-number \
--id "phone-number-id-XXXXXXXXXXXXXXXXXXXX"
- Phone must be verified and active
- Quality rating affects sending limits
Step 3: Inspect Templates
aws socialmessaging list-whatsapp-message-templates --id "waba-XXXXXXXXXXXXXXXXXXXX"
Look for:
REJECTEDtemplates — recreate with compliant contentPENDING> 24h — create a new template- Category mismatch (submitted UTILITY, now shows MARKETING) — reclassified by Meta
Step 4: Verify Event Destinations
aws sns list-subscriptions-by-topic \
--topic-arn "arn:aws:sns:us-east-1:123456789012:whatsapp-events"
- All subscriptions must be
Confirmed - Verify subscription endpoints are authorized personnel/systems; use HTTPS-only endpoints
- If no event destination configured, delivery failures are invisible
Step 5: Check Service Quotas
aws service-quotas get-service-quota \
--service-code social-messaging \
--quota-code L-XXXXXXXX
Review service quotas for quota codes and defaults. New WABAs have lower limits that increase with quality rating.
Step 6: Check CloudTrail for API Errors
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).
Common Error Patterns
| 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 |
Meta Error Codes
Common codes — see Meta's error reference 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 |
Quick Checklist
- ✅ WABA registration COMPLETE
- ✅ Phone number verified and active
- ✅ Template APPROVED (not PENDING/REJECTED)
- ✅ Template category matches content (not reclassified)
- ✅ Event destinations configured + SNS subscriptions confirmed
- ✅ Recipient has WhatsApp on that number
- ✅ Within 24h window (freeform only)
- ✅ Not exceeding rate limits