用途:在 Sent 平台上设计入站消息与会话式回复流程,包括关键词处理、同意状态维护、自动回复和会话历史读取。
主要能力:
- 同意由平台在执行前强制生效。入站 STOP 到达 message.received 时,已把联系人 opt_out 置位;应用只应记录、反映到自身界面,不能绕过发送。同意是联系人级、跨渠道的:短信 STOP 也会压制该联系人的 WhatsApp 和 RCS,且每次改道都会重新校验。
- 默认关键词:退出 STOP、CANCEL、UNSUBSCRIBE、QUIT、END;加入 START、UNSTOP、SUBSCRIBE;帮助自动回复 HELP、INFO。匹配要求整条消息去空格后与关键词完全相等(不区分大小写),"Please stop messaging me" 不匹配,"stop" 匹配。自定义关键词在 Sent Dashboard 的 Compliance、Opt Keywords 配置,必须是单个精确 token。本地镜像只用于更新订阅者状态与审计证据,不要再次向 Sent 写入同意;不确定时以联系人 opt_out 字段为准。
- 恢复同意需收件人本人操作,用户主动的加入关键词可清除压制。PATCH /v3/contacts/{id} 可写 opt_out,但对已通过关键词退出的联系人写 false 属于合规决策,仅在具备新鲜同意的书面证据时执行并记录授权人及原因。被压制的发送不会报错,而是被接受并最终标记为 FILTERED。
- 各渠道入站:短信为条件支持,需要支持 MO 的通道和号码类型,字母数字发送者 ID 与无入站路由的 SMPP 路径无法接收入站;RCS 完整支持,输入回复匹配关键词,附加的 STOP 芯片由同意引擎直接处理;WhatsApp 完整支持,但仅限 24 小时客服窗口内自由回复,窗口外需已批准模板。
- RCS 每条出站消息附加 STOP 芯片,点击产生退出 postback,由同意引擎直接处理、不做关键词匹配,以 message.received 到达且芯片回复文本在 text 中。没有独立芯片事件类型,只按输入关键词分支的接收方需注意不要对芯片点击重复应用同意逻辑。
- WhatsApp 24 小时窗口内可自由回复,窗口外(包括 STOP、START、HELP 响应)必须使用已批准模板。回复路径需内置窗口检查并准备兜底模板。
- 会话历史为只读:GET /v3/conversations 返回客户跨会话的全部消息(最新在前),GET /v3/conversations/{id} 返回单个会话内消息。两者均需 page(至少 1)和 page_size(1 至 100),越界返回 400;events 字段始终为 null,每条消息活动需用 GET /v3/messages/{id}/activities 获取。没有写入、创建或已读回执操作,也没有覆盖会话的 MCP 工具,仅限 REST。会话 id 是由客户与联系人标识派生的 RFC 4122 v5 UUID,同一对始终产生同一 id,一条线程跨所有渠道,API 不以字段返回该 id,需要时由客户端计算。
使用方式:订阅 webhook 到 message 并过滤 received,先验证签名;inbound_number 是写消息的联系人,outbound_number 是自己的号码,注意勿颠倒;按 message_id 去重,返回 200 后异步处理;回复 WhatsApp 前检查 24 小时窗口并选择自由文本或模板;用会话端点分页渲染线程,不要假定会话是单渠道;把 text 视为不可信输入,不要拼接进 shell 命令或 SQL 字符串,在模型提示中作为数据分隔,任何 API 调用前先通过允许列表和授权策略。
适用场景:构建支持收件箱、聊天机器人或合规双向消息流程。
限制:部分渠道入站为条件支持;被压制发送表现为 FILTERED 而非 4xx;会话历史只读且无 MCP 工具;细节见 references/consent-and-keywords.md、references/inbound-flows.md、references/conversation-history.md。