aws-social-messaging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过AWS End User Messaging Social实现WhatsApp消息功能：模板管理、消息发送、媒体处理、事件目标配置以及投递故障排查。

推荐配置： 使用AWS MCP server实现沙箱执行、审计日志记录和企业级管控。

不使用AWS MCP的情况： 该技能可与任何具备AWS CLI访问权限的Agent配合使用。所有命令均采用标准AWS CLI语法。

Common Tasks

常见任务

1. Verify Dependencies

1. 验证依赖项

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)

约束条件：

推荐使用AWS MCP server以实现无缝API执行，但非必需——所有命令均采用标准AWS CLI语法
必须验证AWS CLI已安装并配置了适当的凭证
应建议用户使用带有临时凭证的IAM角色
若缺少任何必需工具，必须告知用户并说明安装/配置方法
必须询问用户是否要在缺少工具的情况下继续操作
若
```
aws socialmessaging
```
子命令无法被识别，用户必须升级到最新版本的AWS CLI

所需IAM权限（限定于特定WABA和电话号码ARN）：

模板：

social-messaging:CreateWhatsAppMessageTemplate

social-messaging:GetWhatsAppMessageTemplate

social-messaging:ListWhatsAppMessageTemplates

social-messaging:UpdateWhatsAppMessageTemplate

social-messaging:DeleteWhatsAppMessageTemplate

social-messaging:ListWhatsAppTemplateLibrary

social-messaging:CreateWhatsAppMessageTemplateFromLibrary

消息发送：
```
social-messaging:SendWhatsAppMessage
```

媒体：

social-messaging:PostWhatsAppMessageMedia

social-messaging:CreateWhatsAppMessageTemplateMedia

social-messaging:GetWhatsAppMessageMedia

social-messaging:DeleteWhatsAppMessageMedia

事件：

social-messaging:PutWhatsAppBusinessAccountEventDestinations

诊断：

social-messaging:GetLinkedWhatsAppBusinessAccount

social-messaging:GetLinkedWhatsAppBusinessAccountPhoneNumber

social-messaging:ListLinkedWhatsAppBusinessAccounts

支持：

sns:ListSubscriptionsByTopic

iam:PassRole

（用于事件目标角色）

2. Manage Templates

2. 管理模板

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.

创建、更新和删除消息模板（实用类、营销类、认证类）。

create-whatsapp-message-template

：需对

--template-definition

进行base64编码（blob类型）

create-whatsapp-message-template-from-library

：使用Meta预审批的模板库模板

```
list-whatsapp-template-library
```
：浏览可用的库模板

get-whatsapp-message-template

：通过

--id

（WABA）和

--meta-template-id

检索模板详情

```
update-whatsapp-message-template
```
：修改现有模板内容

delete-whatsapp-message-template

：需要

--template-name

（而非

--meta-template-name

）；必须始终包含

--delete-all-languages

参数

list-whatsapp-message-templates

：响应字段为

templateStatus

和

templateCategory

（而非

status

category

）

包含
```
{{N}}
```
参数的模板必须添加
```
"parameter_format": "positional"
```
（例外：认证类模板——Meta会自动处理OTP参数）以及
```
"example"
```
字段
Meta会审核所有模板（耗时数分钟至24小时）；不得使用处于PENDING/REJECTED状态的模板
选择错误的模板类别会导致重新分类（如UTILITY→MARKETING），进而影响定价——请参考managing-templates.md — 选择正确类别以了解UTILITY、MARKETING和AUTHENTICATION类别的选择指南
在创建模板前，必须与用户确认预期的类别（UTILITY、MARKETING或AUTHENTICATION）——若用户选择不明确，需解释分类标准及重新分类的风险

详情请见managing-templates.md。

3. Send Messages

3. 发送消息

Template Messages (no 24h restriction)

模板消息（无24小时限制）

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

适用场景：交易更新（实用类）、促销活动（营销类）、验证码（认证类）
需要收集的信息：电话号码ID、收件人（带
```
+
```
的E.164格式）、模板名称、语言、参数
营销类模板可包含图片头部
```
--message
```
为blob类型——必须对JSON进行base64编码

Freeform Messages (24h window required)

自由格式消息（需在24小时窗口内）

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.

适用场景：在用户最后一条入站消息的24小时内回复客户服务请求
支持类型：文本、图片、文档、视频、音频——请参考WhatsApp Cloud API媒体参考了解支持的格式和大小限制
无API可检查窗口状态——用户必须通过日志或事件历史确认
媒体URL必须是可公开访问的HTTPS链接，且在消息有效期30天内保持可用（Meta可随时重新获取）。对于敏感内容（收据、发票、个人身份信息），请通过
```
post-whatsapp-message-media
```
上传并通过媒体ID引用——预签名URL无法满足30天可用性要求

所有消息发送的约束条件：

在执行任何API调用前，需验证参数格式：
- 电话号码ID需匹配
```
phone-number-id-*
```
  格式
- WABA ID需匹配
```
waba-*
```
  格式
- 收件人号码为带
```
+
```
  前缀的E.164格式（例如
```
+14155551234
```
  ），或通过
```
"recipient"
```
  字段使用业务范围用户ID（BSUID）
- 模板名称仅包含小写字母、数字和下划线
- 语言代码使用Meta的下划线分隔格式（例如
```
en_US
```
  ,
```
pt_BR
```
  ）
- ```
--meta-api-version
```
  为
```
v{Major}.{Minor}
```
  格式（例如
```
v21.0
```
  ）
JSON体中的
```
"messaging_product"
```
必须设置为
```
"whatsapp"
```
；请查看Meta Graph API更新日志了解支持的Meta Graph API版本
```
--message
```
为blob类型——必须对JSON负载进行base64编码
成功返回
```
messageId
```
仅表示消息已进入队列，不代表已投递
必须一次性提示用户提供所有必填参数
必须接受以单个值、JSON对象或文件引用形式提供的参数
执行前必须解释每个步骤
执行前应与用户确认所有参数
必须尊重用户终止操作的决定
未经用户确认，批量发送消息不得超过5条
不得直接创建或访问凭证

详情请见sending-messages.md。

4. Manage Media

4. 管理媒体

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.

上传、检索和删除用于消息及模板头部的媒体文件。

```
post-whatsapp-message-media
```
：上传媒体，返回可重复使用的媒体ID
```
create-whatsapp-message-template-media
```
：专门为模板头部上传媒体
```
get-whatsapp-message-media
```
：通过ID检索媒体元数据/URL
```
delete-whatsapp-message-media
```
：删除已上传的媒体

详情请见managing-media.md。

5. Configure Event Destinations

5. 配置事件目标

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.

设置投递追踪、模板状态通知和重新分类告警。

设置投递追踪、模板状态通知和重新分类告警。一个WABA只能配置一个事件目标。请参考configuring-event-destinations.md了解前提条件（IAM角色、带KMS加密的SNS主题、仅HTTPS的订阅端点、条件键）及完整安全管控措施。

6. Troubleshoot Delivery

6. 排查投递问题

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.

诊断流程：WABA状态 → 电话号码 → 模板 → 事件目标 → 配额。

```
get-linked-whatsapp-business-account
```
：注册状态必须为COMPLETE

get-linked-whatsapp-business-account-phone-number

：验证电话号码健康状态

```
list-linked-whatsapp-business-accounts
```
：列出所有WABA
模板被重新分类：可通过事件目标（实时）或列出模板并对比类别检测；需删除并重新创建模板
24小时窗口已过期：改用模板消息
速率限制：新WABA的限制较低；限制会随消息质量提升而增加
收件人未使用WhatsApp：消息会被静默丢弃

详情请见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

访问被拒绝：验证IAM权限是否限定于WABA/电话号码ARN
模板被拒绝：模板内容必须匹配类别；需包含
```
parameter_format
```
和
```
example
```
字段
模板被重新分类：配置事件目标以检测；删除并重新创建模板
24小时窗口已过期：改用模板消息而非自由格式消息
发送失败：
```
--origination-phone-number-id
```
是ID（而非电话号码）；收件人需为带
```
+
```
的E.164格式
已入队列但未投递：200状态码表示已入队列；配置事件目标以获取状态
媒体URL无法访问：必须是可公开访问的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

使用最小权限IAM策略，限定于特定
```
social-messaging:
```
操作及WABA/电话号码ARN
使用临时凭证（IAM角色）而非长期访问密钥
将密钥存储在AWS Secrets Manager或Parameter Store中——切勿存储在代码或环境变量中
启用CloudTrail以审计所有
```
social-messaging
```
API调用；使用KMS CMK加密日志
对事件目标的SNS主题进行KMS加密（回调包含收件人元数据）
若监控social-messaging活动，使用KMS加密CloudWatch日志
避免在模板参数和自由格式消息内容中包含敏感数据（它们会出现在CloudTrail日志中）
验证收件人电话号码以防止未经授权的消息发送
验证SNS订阅端点是否经团队授权——在确认订阅前，验证所有订阅的电子邮件地址和系统是否属于有权接收敏感投递状态和收件人元数据的人员/系统。仅使用HTTPS端点
为SNS主题策略添加条件键（
```
aws:SourceArn
```
,
```
aws:SourceAccount
```
）以防止混淆代理攻击
通过服务配额和CloudWatch告警对发送速率实施速率限制

aws-social-messaging

Original

Translation

AWS End User Messaging Social — WhatsApp

AWS End User Messaging Social — WhatsApp

Overview

概述

Common Tasks

常见任务

1. Verify Dependencies

1. 验证依赖项

2. Manage Templates

2. 管理模板

3. Send Messages

3. 发送消息

Template Messages (no 24h restriction)

模板消息（无24小时限制）

Freeform Messages (24h window required)

自由格式消息（需在24小时窗口内）

4. Manage Media

4. 管理媒体

5. Configure Event Destinations

5. 配置事件目标

6. Troubleshoot Delivery

6. 排查投递问题

Quick Reference — Common Errors

快速参考——常见错误

Security Considerations

安全注意事项

Additional Resources

额外资源