/aws-social-messaging

name: aws-social-messaging
description: Manages WhatsApp messaging through AWS End User Messaging Social. Covers managing templates (create, update, delete, library), sending messages (utility/marketing/auth templates and freeform), uploading and managing media, configuring event destinations for delivery tracking, and troubleshooting delivery failures. Applicable when a user needs to send WhatsApp messages, create or manage templates, upload media, configure delivery notifications, or diagnose messaging issues.
version: 1

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](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/mcp-server.html) 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](references/managing-templates.md) 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](references/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](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media) 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_