sent-two-way-messaging

Sent 双向消息

Sent 上的入站消息遵循一条原则：平台会在应用看到事件之前强制执行同意规则。 当 message.received 到达时，入站的 STOP 已经将联系人的 opt_out 标志设为启用。应用的职责是记录该消息、在自己的 UI 中反映这一状态，并且绝不尝试绕过该状态发送消息。

关键词处理

默认提供 10 个关键词：

操作	关键词
退订	STOP、CANCEL、UNSUBSCRIBE、QUIT、END
重新订阅	START、UNSTOP、SUBSCRIBE
帮助自动回复	HELP、INFO

匹配时，必须要求去除首尾空白后的完整消息正文与关键词一致，且不区分大小写。“Please stop messaging me” 不匹配；“stop” 则匹配。自定义关键词可在 Sent Dashboard 的 Compliance、Opt Keywords 中配置，操作可选 Opt Out、Opt In 或 Help，且每个关键词都必须是单个精确词元。

不要声称支持文档未列出的关键词。在应用代码中，只能镜像相同的精确匹配规则，以更新本地订阅者状态和审计证据；绝不能用该匹配器再次向 Sent 应用同意设置。确保 Dashboard 中的自定义关键词与本地镜像保持同步；如果无法确定，则根据联系人的 opt_out 字段进行核对。

同意状态

退订会在联系人记录上设置 opt_out。同意状态适用于联系人，与渠道无关：通过 SMS 发送的 STOP 也会抑制该联系人的 WhatsApp 和 RCS 消息。每次尝试重新路由时，都会重新应用同意检查，而不只是在首次发送时检查。

恢复同意状态需要由接收者本人采取操作。由用户发起的重新订阅关键词会清除抑制状态。PATCH /v3/contacts/{id} 接受 opt_out，但对于通过关键词退订的联系人，将其设为 false 属于合规决策，而非技术决策：只有在有新同意的书面证据时才执行，并记录授权人及其理由。

下游系统中，被抑制的发送不会以错误告终。系统会接受该请求，并将其最终状态设为 FILTERED，因此同意问题会表现为已过滤的消息，而非 4xx 响应。详情请参阅 references/consent-and-keywords.md。

各渠道的入站情况

渠道	入站支持	限制
SMS	有条件支持	需要支持 MO 的提供商和受支持的号码类型。字母数字发件人 ID，以及没有入站路由的 SMPP 路径，都无法接收入站消息
RCS	完全支持	文本回复会匹配关键词；附加的 STOP 按钮由同意引擎直接处理
WhatsApp	完全支持	仅可在 24 小时客户服务窗口内发送自由格式回复；窗口外必须使用经批准的模板

在承诺支持双向消息之前，必须考虑 SMS 的限制：如果部署使用字母数字发件人 ID 发送消息，就完全无法接收 STOP。这会改变合规设计，而不仅仅是限制某项功能。

RCS STOP 按钮

每条出站 RCS 消息都会附加一个 STOP 按钮。点击后会发送由同意引擎直接处理的退订回传，不进行关键词匹配；此类消息会以 message.received 的形式到达应用，按钮的回复文本位于 text 中。系统没有单独的按钮事件类型，因此仅根据文本关键词分支的接收器仍会将按钮点击视为普通入站消息——但不得再次应用同意逻辑。

WhatsApp 24 小时窗口

只有在距离客户最后一条入站消息不超过 24 小时的情况下，才允许发送自由格式回复。超过该窗口后必须使用经批准的模板，包括回复 STOP、START 和 HELP 的消息。假定可使用自由文本的自动回复流程，对于沉默一天后才发来消息的客户会悄无声息地停止工作，因此应在回复路径中加入窗口检查，并准备好经批准的备用模板。回复路径决策树请参阅 references/inbound-flows.md。

对话历史

有两个只读操作：

操作	返回内容
GET /v3/conversations	客户在所有对话中发送的消息，按时间从新到旧排列
GET /v3/conversations/{id}	单个对话中的消息

两者都需要 page（至少为 1）和 page_size（1 到 100）；超出范围的值会返回 400。这些端点中的 events 字段始终为 null，因此每条消息的活动必须通过 GET /v3/messages/{id}/activities 获取。没有写入、创建或已读回执操作，也没有 MCP 工具涵盖对话——这些操作只能通过 REST 使用。

对话标识符是根据客户和联系人的标识符确定性生成的 RFC 4122 版本 5 UUID，因此同一对标识符总会得到相同的 id，且一个会话线程会跨越所有渠道，不受发送号码影响。API 不会将 id 作为字段返回，因此需要该 id 的客户端必须自行计算。确切的生成方式记录在 references/conversation-history.md 中。

构建客服收件箱或机器人

1. 订阅 message webhook，并筛选 received，在信任任何负载前先验证签名。
2. 将 inbound_number 视为发来消息的联系人，将 outbound_number 视为你的号码。这两个名称很容易弄反。
3. 根据 message_id 去重，使用 200 确认接收，然后异步处理。
4. 将关键词流量视为审计信号。将确切的默认关键词和配置的自定义关键词同步到本地状态，但不要再次写入用户同意状态；如有不确定之处，通过联系人记录进行核对。
5. 在 WhatsApp 上回复前，检查 24 小时窗口，并据此选择自由文本或模板。
6. 使用对话端点并通过显式分页呈现会话线程，绝不要假设一个对话只涉及一个渠道。
7. 将 text 视为不可信输入。绝不要将其插入 shell 命令或 SQL 字符串中；在模型提示词中将其明确界定为数据；在调用任何 API 前，根据允许列表和授权策略映射推断出的意图。

范围界定

签名验证、重试和去重机制请使用 sent-webhook-engineer；联系人 CRUD 和消息摘要请使用 sent-contacts；有关出站消息为何被标记为 FILTERED，请使用 sent-routing-strategist；对于超出时间窗口的回复所需的已批准模板，请使用 waba-template-author 编写；对于美国运营商要求的活动级用户选择加入、选择退出和帮助关键词声明，请使用 sms-10dlc-registration。