aws-social-messaging

AWS End User Messaging Social — WhatsApp

Overview

WhatsApp messaging via AWS End User Messaging Social: template management, sending, media handling, event destinations, and delivery troubleshooting.

Recommended setup: Use the AWS MCP server for sandboxed execution, audit logging, and enterprise controls.

Without AWS MCP: This skill works with any agent that has AWS CLI access. All commands use standard AWS CLI syntax.

Common Tasks

1. Verify Dependencies

Constraints:

• The AWS MCP server is recommended for seamless API execution but not required — all commands use standard AWS CLI syntax
• You MUST verify the AWS CLI is installed and configured with appropriate credentials
• You SHOULD recommend the user assume an IAM role with ephemeral credentials
• You MUST inform the user if any required tool is missing and how to install/configure it
• You MUST ask the user if they want to proceed despite any missing tools
• If the aws socialmessaging subcommand is not recognized, the user must update to the latest AWS CLI version
• Required IAM permissions (scope to specific WABA and phone number ARNs):
• Templates: social-messaging:CreateWhatsAppMessageTemplate, social-messaging:GetWhatsAppMessageTemplate, social-messaging:ListWhatsAppMessageTemplates, social-messaging:UpdateWhatsAppMessageTemplate, social-messaging:DeleteWhatsAppMessageTemplate, social-messaging:ListWhatsAppTemplateLibrary, social-messaging:CreateWhatsAppMessageTemplateFromLibrary
• Sending: social-messaging:SendWhatsAppMessage
• Media: social-messaging:PostWhatsAppMessageMedia, social-messaging:CreateWhatsAppMessageTemplateMedia, social-messaging:GetWhatsAppMessageMedia, social-messaging:DeleteWhatsAppMessageMedia
• Events: social-messaging:PutWhatsAppBusinessAccountEventDestinations
• Diagnostics: social-messaging:GetLinkedWhatsAppBusinessAccount, social-messaging:GetLinkedWhatsAppBusinessAccountPhoneNumber, social-messaging:ListLinkedWhatsAppBusinessAccounts
• Supporting: sns:ListSubscriptionsByTopic, iam:PassRole (for event destination role)

2. Manage Templates

Create, update, and delete message templates (utility, marketing, authentication).

• create-whatsapp-message-template: base64-encode --template-definition (blob type)
• create-whatsapp-message-template-from-library: use pre-approved Meta library templates
• list-whatsapp-template-library: browse available library templates
• get-whatsapp-message-template: retrieve template details by --id (WABA) and --meta-template-id
• update-whatsapp-message-template: modify existing template content
• delete-whatsapp-message-template: requires --template-name (NOT --meta-template-name); always include --delete-all-languages
• list-whatsapp-message-templates: response fields are templateStatus and templateCategory (NOT status/category)
• Templates with {{N}} parameters MUST include "parameter_format": "positional" (exception: AUTHENTICATION — Meta handles OTP parameters automatically) and "example"
• Meta reviews all templates (minutes to 24h); MUST NOT send with PENDING/REJECTED
• Choosing the wrong category causes reclassification (UTILITY → MARKETING) which changes pricing — see managing-templates.md — Choosing the Right Category for guidance on selecting UTILITY vs MARKETING vs AUTHENTICATION
• You MUST confirm the intended category (UTILITY, MARKETING, or AUTHENTICATION) with the user before creating a template — explain the categorization criteria and reclassification risk if the choice is ambiguous

See managing-templates.md.

3. Send Messages

Template Messages (no 24h restriction)

• Use for: transactional updates (utility), promotions (marketing), verification codes (authentication)
• Collect: phone number ID, recipient (E.164 with +), template name, language, parameters
• Marketing templates may include image headers
• --message is blob type — MUST base64-encode JSON

Freeform Messages (24h window required)

• Use for: customer service replies within 24h of customer's last inbound message
• Supports: text, image, document, video, audio — see WhatsApp Cloud API media reference for supported format and size constraints
• No API to check window status — user must confirm from logs or event history
• Media URLs MUST be publicly accessible HTTPS and remain available for the full 30-day message availability window (Meta can re-fetch anytime). For sensitive content (receipts, invoices, PII), upload via post-whatsapp-message-media and reference by media ID instead — presigned URLs cannot satisfy the 30-day availability requirement

Constraints for all sends:

• Before executing any API call, validate parameter formats:
• Phone number IDs match phone-number-id-* pattern
• WABA IDs match waba-* pattern
• Recipient numbers are E.164 with + prefix (e.g., +14155551234), or Business-Scoped User ID (BSUID) via the "recipient" field
• Template names contain only lowercase letters, numbers, and underscores
• Language codes use Meta's locale format with underscores (e.g., en_US, pt_BR)
• --meta-api-version is v{Major}.{Minor} format (e.g., v21.0)
• "messaging_product" MUST be "whatsapp" in the JSON body; check Meta's Graph API changelog for the supported Meta Graph API version
• --message is blob type — MUST base64-encode the JSON payload
• A successful messageId means queued, not delivered
• You MUST ask for all required parameters upfront in a single prompt
• You MUST accept parameters as individual values, JSON objects, or file references
• You MUST explain each step before executing
• You SHOULD confirm all parameters with the user before executing
• You MUST respect the user's decision to abort
• You MUST NOT send more than 5 messages per batch without user confirmation
• You MUST NOT create or access credentials directly

See sending-messages.md.

4. Manage Media

Upload, retrieve, and delete media for messages and template headers.

• post-whatsapp-message-media: upload media, returns reusable media ID
• create-whatsapp-message-template-media: upload media specifically for template headers
• get-whatsapp-message-media: retrieve media metadata/URL by ID
• delete-whatsapp-message-media: remove uploaded media

See managing-media.md.

5. Configure Event Destinations

Set up delivery tracking, template status notifications, and reclassification alerts.

Set up delivery tracking, template status notifications, and reclassification alerts. A WABA can only have one event destination. See configuring-event-destinations.md for prerequisites (IAM role, SNS topic with KMS encryption, HTTPS-only subscription endpoints, condition keys) and full security controls.

6. Troubleshoot Delivery

Diagnostic flow: WABA status → phone number → templates → event destinations → quotas.

• get-linked-whatsapp-business-account: registration MUST be COMPLETE
• get-linked-whatsapp-business-account-phone-number: verify phone number health
• list-linked-whatsapp-business-accounts: list all WABAs
• Template reclassified: detectable via event destinations (real-time) or by listing templates and comparing categories; delete and recreate
• 24h window expired: use template message instead
• Rate limiting: new WABAs have lower limits; increases with quality
• Recipient without WhatsApp: silently dropped

See troubleshooting-delivery.md.

Quick Reference — Common Errors

• Access denied: verify IAM permissions scoped to WABA/phone number ARNs
• Template rejected: body must match category; include parameter_format and example
• Template reclassified: configure event destinations to detect; delete and recreate
• 24h window expired: use template message instead of freeform
• Send fails: --origination-phone-number-id is the ID (not phone number); recipient E.164 with +
• Queued but not delivered: 200 = queued; configure event destinations for status
• Media URL inaccessible: must be publicly accessible HTTPS

Security Considerations

• Use least-privilege IAM policies scoped to specific social-messaging: actions and WABA/phone number ARNs
• Use ephemeral credentials (IAM roles) instead of long-lived access keys
• Store secrets in AWS Secrets Manager or Parameter Store — never in code or environment variables
• Enable CloudTrail for auditing all social-messaging API calls; encrypt logs with KMS CMK
• Encrypt SNS topics for event destinations with KMS (callbacks contain recipient metadata)
• Encrypt CloudWatch Logs with KMS if monitoring social-messaging activity
• Avoid sensitive data in template parameters and freeform message content (they appear in CloudTrail logs)
• Validate recipient phone numbers to prevent unauthorized messaging
• Verify SNS subscription endpoints are authorized by your team — validate that all subscribed email addresses and systems belong to personnel/systems that should receive sensitive delivery status and recipient metadata before confirming subscriptions. Use HTTPS-only endpoints
• Add condition keys (aws:SourceArn, aws:SourceAccount) to SNS topic policies to prevent confused deputy attacks
• Implement rate limiting via service quotas and CloudWatch alarms on send rates

Additional Resources

• AWS End User Messaging Social User Guide
• AWS CLI socialmessaging Reference
• Getting Started with WhatsApp
• Managing Event Destinations
• Service Quotas
• IAM Security Best Practices
• Confused Deputy Prevention
• SNS Data Protection Best Practices
• AWS Well-Architected Security Pillar