在 Sent 平台上处理双向消息（STOP/HELP…

当需要处理 Sent 的 message.received 事件、实现 STOP/HELP 行为、恢复同意状态、构建客服收件箱或聊天机器人、分页查询对话历史时使用。

适用场景

解决思路

1. 理解核心规则：同意由平台在应用看到事件之前强制执行——入站 STOP 到达 message.received 时，联系人的 opt_out 标志已被平台翻转；应用只负责记录、在自身 UI 中反映，绝不尝试绕过它发送。
2. 关键词处理：默认关键词分三类——退订 STOP、CANCEL、UNSUBSCRIBE、QUIT、END；重新订阅 START、UNSTOP、SUBSCRIBE；帮助自动回复 HELP、INFO。
3. 匹配规则：要求整条去除首尾空白后的消息正文与关键词完全相等（大小写不敏感）——"Please stop messaging me" 不匹配，"stop" 匹配。
4. 自定义关键词在 Sent Dashboard 的 Compliance、Opt Keywords 下配置，动作可选 Opt Out、Opt In 或 Help，每个必须是单个精确 token。
5. 不要声明文档集合之外的关键词；在应用代码中仅用同样的精确匹配规则更新本地订阅者状态和审计证据，绝不用该匹配器再次向 Sent 应用同意；保持 Dashboard 自定义关键词与本地镜像同步，不确定时以联系人的 opt_out 字段为准。
6. 同意状态：退订会在联系人记录上设置 opt_out；同意是联系人级别且跨渠道的——通过 SMS 发送的 STOP 也会抑制该联系人的 WhatsApp 和 RCS；同意门控在每次重路由尝试时都会重新应用，而不只是首次发送时。
7. 恢复同意需要收件人自己的动作：用户主动发送的 opt-in 关键词会清除抑制；PATCH /v3/contacts/{id} 接受 opt_out，但对通过关键词退订的联系人写入 false 是合规决策而非技术决策——只有在有新鲜同意的书面证据时才这样做，并记录授权人及原因。
8. 注意被抑制的发送不会报错，而是被接受并最终状态为 FILTERED，因此同意问题表现为被过滤的消息而非 4xx 响应。
9. 了解各渠道入站现实：SMS 为条件性——需要支持 MO 的供应商和受支持的号码类型，字母数字发送者 ID 和无入站路由的 SMPP 路径永远收不到入站消息；RCS 为完整支持——类型化回复匹配关键词，附加的 STOP 芯片由同意引擎直接处理；WhatsApp 为完整支持——仅在 24 小时客服窗口内允许自由格式回复，窗口外需要已批准的模板。
10. 在承诺双向行为前注意 SMS 限制：使用字母数字发送者 ID 的部署根本无法收到 STOP，这会改变合规设计而不只是限制功能。
11. RCS STOP 芯片：每条出站 RCS 消息都会附加一个 STOP 芯片；点击携带退订 postback，由同意引擎直接处理、无需关键词匹配，并以 message.received 到达应用、芯片回复文本在 text 中；没有单独的芯片事件类型，因此只按类型化关键词分支的接收方仍会把芯片点击当作普通入站消息——且不得对其重新应用同意逻辑。
12. WhatsApp 24 小时窗口：仅在客户最后一条入站消息后 24 小时内允许自由格式回复；窗口外需要已批准的模板，包括对 STOP、START、HELP 的回复；把窗口检查构建进回复路径，并常备一个已批准的备用模板。
13. 对话历史：两个只读操作——GET /v3/conversations 返回客户跨所有对话的全部消息（最新在前），GET /v3/conversations/{id} 返回单个对话内的消息；两者都要求 page（至少 1）和 page_size（1 到 100），超出范围返回 400。
14. 这些端点的 events 字段始终为 null，因此每条消息的活动必须来自 GET /v3/messages/{id}/activities；没有写入、创建或已读回执操作，也没有 MCP 工具覆盖对话——仅限 REST。
15. 对话标识符是由客户和联系人标识符派生的确定性 RFC 4122 版本 5 UUID，因此同一对始终产生相同 id，且一个线程跨所有渠道、与发送号码无关；API 从不将其作为字段返回，需要它的客户端需自行计算。
16. 构建客服收件箱或机器人：订阅 webhook 到 message 并过滤 received，在信任任何负载前验证签名。
17. 读取 inbound_number 为来信联系人、outbound_number 为自己的号码——命名很容易弄反。
18. 按 message_id 去重，用 200 确认，然后异步处理。
19. 把关键词流量视为审计信号：将默认和已配置的自定义关键词精确镜像到本地状态，但不要发出第二次同意写入；通过联系人记录协调不确定性。
20. 在 WhatsApp 上回复前，检查 24 小时窗口并相应选择自由文本或模板。
21. 用对话端点渲染线程并显式分页，绝不假设对话是单渠道的。
22. 把 text 视为不可信输入：绝不将其插入 shell 命令或 SQL 字符串，在模型提示中将其作为数据分隔，并在任何 API 调用前通过允许列表和授权策略映射推断的意图。

适用边界 · 注意事项

• 需要处理签名验证、重试和去重机制时，改用 sent-webhook-engineer。
• 需要联系人 CRUD 和消息摘要时，改用 sent-contacts；需要排查出站消息为何被 FILTERED 时，改用 sent-routing-strategist。
• 需要编写窗口外回复所需的已批准模板时，改用 waba-template-author；需要美国运营商要求的活动级 opt-in、opt-out 和 help 关键词声明时，改用 sms-10dlc-registration。