aws-social-messaging

AWS End User Messaging Social — WhatsApp

概览

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

推荐设置： 使用 AWS MCP 服务，实现沙盒化执行、审计日志记录和企业级控制。

不使用 AWS MCP： 此技能适用于任何拥有 AWS CLI 访问权限的 Agent。所有命令均使用标准 AWS CLI 语法。

常见任务

1. 验证依赖项

限制：

• 推荐使用 AWS MCP 服务，以便无缝执行 API，但并非必需 — 所有命令均使用标准 AWS CLI 语法
• 你 MUST 验证已安装 AWS CLI，且已使用适当的凭证完成配置
• 你 SHOULD 建议用户使用具有临时凭证的 IAM 角色
• 如果缺少任何必需工具，你 MUST 告知用户，并说明如何安装或配置
• 如果缺少任何工具，你 MUST 询问用户是否仍要继续
• 如果无法识别 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. 管理模板

创建、更新和删除消息模板（实用工具、营销、身份验证）。

• 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}} 参数的模板 MUST 包含 "parameter_format": "positional"（例外：AUTHENTICATION — Meta 会自动处理 OTP 参数）和 "example"
• Meta 会审核所有模板（耗时几分钟至 24 小时）；状态为 PENDING/REJECTED 时 MUST NOT 发送消息
• 选择错误的类别会导致重新分类（UTILITY → MARKETING），进而改变定价 — 请参阅 managing-templates.md — 选择正确的类别，了解如何选择 UTILITY、MARKETING 或 AUTHENTICATION
• 创建模板前，你 MUST 与用户确认预期类别（UTILITY、MARKETING 或 AUTHENTICATION）；如果选择存在歧义，请说明类别判定标准和重新分类风险

请参阅 managing-templates.md。

3. 发送消息

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

• 用途：事务性更新（实用信息）、促销活动（营销）、验证码（身份验证）
• 收集：电话号码 ID、收件人（E.164 格式，带 +）、模板名称、语言、参数
• 营销模板可以包含图片标题
• --message 是 blob 类型 — 必须对 JSON 进行 base64 编码

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

• 用途：在客户最后一条入站消息后的 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" 字段使用 Business-Scoped User 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. 管理媒体

上传、检索和删除消息及模板标题的媒体。

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

请参见 managing-media.md。

5. 配置事件目标

设置送达跟踪、模板状态通知和重新分类提醒。

设置送达跟踪、模板状态通知和重新分类提醒。一个 WABA 只能有一个事件目标。有关前置条件（IAM 角色、使用 KMS 加密的 SNS 主题、仅限 HTTPS 的订阅端点、条件键）和完整安全控制，请参见 configuring-event-destinations.md。

6. 排查消息送达问题

诊断流程：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。

快速参考 — 常见错误

• 拒绝访问：确认 IAM 权限的范围限定为 WABA/电话号码 ARN
• 模板被拒绝：正文必须符合类别；包含 parameter_format 和 example
• 模板重新分类：配置事件目标以便检测；删除后重新创建
• 24 小时窗口已过期：改用模板消息，而不是自由格式消息
• 发送失败：--origination-phone-number-id 应填写 ID（而非电话号码）；收件人号码须为带 + 的 E.164 格式
• 已排队但未送达：200 = 已排队；配置事件目标以获取状态
• 无法访问媒体 URL：必须是可公开访问的 HTTPS URL

安全注意事项

• 使用遵循最小权限原则的 IAM 策略，将权限范围限定为特定的 social-messaging: 操作和 WABA/电话号码 ARN
• 使用临时凭证（IAM 角色），而非长期访问密钥
• 在 AWS Secrets Manager 或 Parameter Store 中存储机密，不要将其写入代码或环境变量
• 启用 CloudTrail，以审计所有 social-messaging API 调用；使用 KMS CMK 加密日志
• 使用 KMS 加密事件目标的 SNS 主题（回调包含收件人元数据）
• 如果要监控 social-messaging 活动，请使用 KMS 加密 CloudWatch Logs
• 避免在模板参数和自由格式消息内容中包含敏感数据（这些内容会出现在 CloudTrail 日志中）
• 验证收件人电话号码，以防止未经授权的消息发送
• 确认 SNS 订阅终端节点已获团队授权 — 确认订阅前，验证所有已订阅的电子邮件地址和系统都属于应接收敏感送达状态和收件人元数据的人员/系统。仅使用 HTTPS 终端节点
• 在 SNS 主题策略中添加条件键（aws:SourceArn、aws:SourceAccount），以防止混淆代理攻击
• 通过服务配额和针对发送速率设置的 CloudWatch 警报实施速率限制

其他资源

• AWS End User Messaging Social 用户指南
• AWS CLI socialmessaging 参考
• WhatsApp 入门
• 管理事件目标
• 服务配额
• IAM 安全最佳实践
• 防止混淆代理问题
• SNS 数据保护最佳实践
• AWS Well-Architected 安全支柱