AutoGineer
Generated banner for AWS Social Messaging
Generated logo for AWS Social Messaging

AWS Social Messaging

AWSOfficialPublished by AWS

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

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.
— the description by AWS

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides an interface for interacting with AWS End User Messaging Social to manage WhatsApp Business Account (WABA) operations. It supports the full lifecycle of WhatsApp messaging, including template management, media handling, event destination configuration for delivery tracking, and diagnostic tools for troubleshooting messaging issues via the AWS CLI.

What it does

  • Create, update, and delete WhatsApp message templates
  • Send utility, marketing, authentication, and freeform messages
  • Upload and manage media assets for messages and template headers
  • Configure event destinations for real-time delivery and status tracking
  • Diagnose messaging issues by checking account and phone number status

When to use it

  • When you need to integrate WhatsApp messaging capabilities into your AWS-based workflows
  • When managing approved message templates for customer communication
  • When setting up automated delivery status notifications via SNS
  • When troubleshooting failed message deliveries or template reclassifications

Advantages

  • Centralized management of WhatsApp messaging through standard AWS CLI commands
  • Supports secure media handling by referencing uploaded media IDs
  • Enables real-time monitoring of message delivery and template status changes
  • Provides structured diagnostic paths for identifying account or delivery issues

Usage examples

“List all available WhatsApp message templates for my WABA.”
The agent will retrieve and display the list of templates, including their current status and category.
“Upload an image to be used in a WhatsApp template header.”
The agent will use the provided S3 file location to upload the media and return a media handle for use in template definitions.
“Configure an SNS topic for tracking WhatsApp message delivery status.”
The agent will guide you through setting up the event destination for your WABA, ensuring the necessary IAM roles and SNS policies are in place.
“Troubleshoot why my WhatsApp messages are not being delivered.”
The agent will check the status of your linked WABA and phone number, and verify if event destinations are configured to provide error logs.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/aws/aws-social-messaging/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip aws-social-messaging.zip -d .agents/skills

Documentation by AWS

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

Files

references/managing-templates.md

Managing WhatsApp Message Templates

Security: Template parameters appear in CloudTrail logs — avoid embedding sensitive data. See SKILL.md — Security Considerations.

Contents

  • Create a Template

  • Create from Library

  • Check Approval Status

  • Get Template Details

  • Update a Template

  • Delete a Template

Create a Template

The --template-definition parameter is a blob type — base64-encode the JSON.

Utility Template (transactional)
TEMPLATE_DEF=$(printf '%s' '{"name":"order_shipment_update","category":"UTILITY","language":"en_US","parameter_format":"positional","components":[{"type":"BODY","text":"Your order #{{1}} has shipped. Track: {{2}}","example":{"body_text":[["ORD-12345","https://example.com/track/12345"]]}}]}' | base64 | tr -d '\n')

aws socialmessaging create-whatsapp-message-template \
  --id "waba-XXXXXXXXXXXXXXXXXXXX" \
  --template-definition "$TEMPLATE_DEF"
Marketing Template (with image header)

First, upload the header image using create-whatsapp-message-template-media to get a media handle (see managing-media.md). Then use the returned handle in the template:

TEMPLATE_DEF=$(printf '%s' '{"name":"seasonal_promotion","language":"en_US","category":"MARKETING","parameter_format":"positional","components":[{"type":"HEADER","format":"IMAGE","example":{"header_handle":["4::aW1hZ2UvanBlZw==:ARb..."]}},{"type":"BODY","text":"Hi {{1}}! Get {{2}}% off all items through {{3}}.","example":{"body_text":[["Jane","25","June 30"]]}}]}' | base64 | tr -d '\n')

aws socialmessaging create-whatsapp-message-template \
  --id "waba-XXXXXXXXXXXXXXXXXXXX" \
  --template-definition "$TEMPLATE_DEF"
Authentication Template (verification codes)
TEMPLATE_DEF=$(printf '%s' '{"name":"login_verification","language":"en_US","category":"AUTHENTICATION","components":[{"type":"BODY","text":"{{1}} is your verification code.","example":{"body_text":[["847293"]]}},{"type":"FOOTER","text":"This code expires in 10 minutes."},{"type":"BUTTONS","buttons":[{"type":"OTP","otp_type":"COPY_CODE","text":"Copy code"}]}]}' | base64 | tr -d '\n')

aws socialmessaging create-whatsapp-message-template \
  --id "waba-XXXXXXXXXXXXXXXXXXXX" \
  --template-definition "$TEMPLATE_DEF"

Authentication templates do not require parameter_format — Meta handles the OTP parameter automatically. The COPY_CODE button type lets recipients tap to copy the code.

Expected Output
{
  "metaTemplateId": "123456789",
  "templateStatus": "PENDING",
  "templateCategory": "UTILITY"
}
Rules

  • parameter_format: MUST be "positional" when using {{N}} parameters

  • example: MUST include sample values for each component — Meta requires this for review

  • UTILITY body MUST be clearly transactional; ambiguous text gets reclassified as MARKETING

  • Template names: lowercase letters, numbers, underscores only

Choosing the Right Category

Meta enforces strict categorization rules. Choosing the wrong category causes reclassification (UTILITY → MARKETING), which changes pricing and may disrupt sending. Select the correct category upfront:

CategoryUse WhenKey Signals
UTILITYConfirming or updating an existing transaction the user initiatedOrder confirmations, shipping updates, appointment reminders, payment receipts, account alerts
MARKETINGPromoting products/services, re-engaging users, or any content the user did not explicitly requestPromotions, discounts, product recommendations, back-in-stock alerts, newsletters, upsells
AUTHENTICATIONSending one-time passwords or verification codesLogin codes, 2FA, account verification — must use OTP button component

Common reclassification triggers (UTILITY → MARKETING):

  • Body text contains promotional language ("Get X% off", "Limited time", "Shop now", "Don't miss")

  • Template includes a call-to-action unrelated to the transaction (e.g., "Check out our new products")

  • Greeting or introduction without referencing a specific user-initiated action

  • Coupon codes or discount offers included alongside transactional content

  • Generic "updates" that aren't tied to a specific order, appointment, or account event

How to avoid reclassification:

  1. Keep UTILITY templates focused on a single transaction — reference the specific order/appointment/account action

  2. Do NOT mix promotional content into transactional templates — create a separate MARKETING template for promotions

  3. Use explicit transaction references in the body: "Your order #{{1}}", "Your appointment on {{1}}", "Your payment of {{1}}"

  4. If in doubt, use MARKETING — it always works; reclassification only happens UTILITY → MARKETING, never the reverse

  5. Configure event destinations to receive TEMPLATE_STATUS_UPDATE events that alert you to reclassifications in real-time

Detecting reclassification after the fact:

  • Via event destinations: "eventType": "TEMPLATE_STATUS_UPDATE" with previousCategory and newCategory

  • Via API: list-whatsapp-message-templates — compare templateCategory against your expected category

  • Recovery: Delete the reclassified template and recreate with corrected content or as MARKETING

Create from Library

Browse and use pre-approved Meta library templates:

aws socialmessaging list-whatsapp-template-library

aws socialmessaging create-whatsapp-message-template-from-library \
  --id "waba-XXXXXXXXXXXXXXXXXXXX" \
  --meta-library-template '{"templateName":"my_order_update","libraryTemplateName":"order_status_update","templateCategory":"UTILITY","templateLanguage":"en_US"}'

Check Approval Status

aws socialmessaging list-whatsapp-message-templates --id "waba-XXXXXXXXXXXXXXXXXXXX"

Response fields are templateStatus and templateCategory (NOT status/category):

{
  "templates": [{
    "templateName": "order_shipment_update",
    "metaTemplateId": "123456789",
    "templateStatus": "APPROVED",
    "templateCategory": "UTILITY",
    "templateLanguage": "en_US"
  }]
}

  • UTILITY: minutes to 24h. MARKETING: hours to 24h.

  • MUST NOT send with PENDING or REJECTED status.

Get Template Details

aws socialmessaging get-whatsapp-message-template \
  --id "waba-XXXXXXXXXXXXXXXXXXXX" \
  --meta-template-id "123456789"

Use this to retrieve component structure before sending an existing template.

Update a Template

aws socialmessaging update-whatsapp-message-template \
  --id "waba-XXXXXXXXXXXXXXXXXXXX" \
  --meta-template-id "123456789" \
  --template-components "$(printf '%s' '[{"type":"BODY","text":"Your order #{{1}} has shipped. Delivery by: {{2}}","example":{"body_text":[["ORD-12345","July 15"]]}}]' | base64 | tr -d '\n')"

The --template-components parameter is a blob type — base64-encode the JSON components array. Updated templates go back to PENDING for Meta re-review.

Delete a Template

⚠️ The delete parameter is --template-name (NOT --meta-template-name, NOT --meta-template-id). There is no --meta-template-name parameter — it does not exist.

aws socialmessaging delete-whatsapp-message-template \
  --id "waba-XXXXXXXXXXXXXXXXXXXX" \
  --template-name "order_shipment_update" \
  --delete-all-languages

Always include --delete-all-languages to avoid InvalidParametersException.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
AWS
Publisher
AWS (Official)
Source
aws/agent-toolkit-for-aws · skills/specialized-skills/customer-communications-skills/aws-social-messaging · commit 0a218f8
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • NOTICE (added by AutoGineer from NOTICE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by AWS or AWS.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download aws-social-messaging.zip