aws-social-messaging

Files (6)

• SKILL.md
• configuring-event-destinations.md · references/
• managing-media.md · references/
• managing-templates.md · references/
• sending-messages.md · references/
• troubleshooting-delivery.md · references/

SKILL.md (first lines)

# 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_product"` MUST be `"whatsapp"` in the JSON body; check [Meta's Graph API changelog](https://developers.facebook.com/docs/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](references/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](references/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](references/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](references/troubleshooting-delivery.md).

## Quick Reference — Common Errors

- **Access denied**: verify IAM permissions scoped to WABA/phone number ARNs

From aws/agent-toolkit-for-aws, Apache-2.0.

More from aws/agent-toolkit-for-aws