事件同步对接方案

一、这套接口解决什么问题

贵方系统中有自己的业务事件，例如订单发货、工单状态变更、优惠券到期提醒等。对接后，这些事件会推送到开言平台，平台把事件内容和会话背景信息一起交给已训练好的 AI Agent，由 AI Agent 按贵方在训练阶段设定的逻辑处理该事件，例如在对应会话中提醒客户、发起主动触达。

举例来说：贵方注册了优惠券到期事件，并在训练时设定收到该事件后，AI Agent 根据会话上下文主动给客户发送话术，引导其使用优惠券。

事件推送的方向始终是：贵方系统 → 开言平台。事件必须挂载在某个具体会话上，因此推送前需要先通过查询会话接口拿到会话 ID（chatId）。

整体流程如下：

需要注意：订阅动作发生在训练阶段。若 AI Agent 尚未订阅某个事件，该事件即使推送成功也不会触发任何动作。

二、对接前置条件

1. 注册事件编码

每个要推送的事件都必须先在开言平台注册，未注册的事件编码会被接口拒绝。

通过下方的注册表单登记，需要提供：

事件名称与描述，说明这个事件在业务上代表什么；

事件编码 eventCode，由贵方自定义，注册后不可随意变更；

payload 的 JSON 结构，即事件内容包含哪些字段、每个字段的含义。

该 JSON 结构同时会作为 AI Agent 理解事件的依据，请尽量使用明确的字段名，并在描述中说明每个字段的含义。

注册表单：https://doc.weixin.qq.com/smartsheet/form/1_wpJawBCQAAhCf5ayp_YgvDUSyb9CdTig_fe3639

2. 训练与订阅

事件注册后，还需在开言平台训练 AI Agent 对该事件的处理逻辑。训练过程中，AI Agent 会主动查询平台中已注册的事件并完成订阅。

订阅是事件生效的前提：订阅成功后，贵方推送的事件才会被 AI Agent 处理；未订阅的事件即使推送接口返回成功，也不会触发任何动作。

3. 鉴权

所有接口通过 URL 上的 accessToken 参数鉴权，获取方式见接口文档：获取 token。

4. 适用范围

目前仅支持企微会话场景。下文涉及的企微 ID 均为明文 ID，贵方可从企微侧直接获取，无需解密。

三、接口一：查询会话

用途

推送事件前，需要知道事件属于哪个会话。本接口按企微侧的信息查询对应的会话，返回会话列表，其中会话 ID（chatId）是后续推送事件的必要参数。

接口文档

完整的请求地址、请求参数与响应说明见：查询会话接口文档。此处只说明对接时必须理解的参数与约束：

通过 type 区分会话类型，0 为单聊，1 为群聊；

单聊匹配二选一：按企微明文 ID 组成对传值（好友明文 ID + 员工明文账号 ID），或按名称组成对传值（好友名称 + 员工名称），任一组都不可只传其一；

群聊匹配同样二选一：群明文企微 ID，或群名称；

所有名称匹配均为精确匹配。

最佳实践：优先传企微明文 ID

名称匹配是精确匹配，名称中包含特殊字符、表情或空格差异都会导致匹配不到。因此建议业务流程中优先通过企微明文 ID 查询会话，仅在拿不到 ID 时才使用名称匹配。

返回结果的理解

返回的会话列表是一个数组。按 ID 匹配时通常只返回一条；按名称匹配时可能返回多条，此时需要贵方根据业务自行确认目标会话。数组元素中的 id 字段即后续推送事件使用的 chatId。

单个会话对象实际返回的字段多于接口文档列出的部分，文档仅列出对接必需的 id 与 name，其余字段请以实际返回为准，不建议依赖未列出的字段。

四、接口二：发送事件

用途

贵方系统中的业务事件发生时，调用本接口把事件推送给开言平台。平台将该事件的内容与背景信息交给 AI Agent 处理。

接口文档

完整的请求地址、请求参数与响应说明见：发送事件接口文档。请求体共五个参数，此处只说明各参数在业务上的含义与注意事项：

eventID：本次事件的唯一 ID，由贵方生成，请保证唯一，建议使用贵方系统内可追溯的编号，便于对账与排查；

eventCode：预先注册的事件编码，见第二节；

bizIDType：业务主键类型，本期固定传 chatID；

bizID：业务主键的值，即查询会话接口返回的会话 ID；

payload：事件内容，JSON 字符串而非 JSON 对象，注意外层引号与内部双引号的转义。字段结构以贵方注册时提交的 schema 为准，由贵方自主定义，平台不做校验，事件能否被正确处理取决于注册时对事件含义与字段含义的描述是否清晰。

五、响应判断与问题排查

接口调用本身失败，例如参数缺失、事件编码未注册：根据响应的 msg 提示修正请求，traceId 一并提供给技术支持；

接口返回成功，但事件未在会话中生效：payload 内容与 AI 的处理逻辑不在接口校验范围内，此类问题需要贵方提供 eventID 与 traceId，联系开言平台技术支持排查；

查询会话匹配不到或匹配出多条：优先检查是否使用了精确名称匹配，建议改用企微明文 ID 匹配。

六、推荐对接顺序

填写注册表单，登记所有要推送的事件编码与 payload 结构；

在开言平台训练事件处理逻辑，并确认 AI Agent 已订阅相关事件；

使用查询会话接口，验证能否按贵方持有的企微明文 ID 查到会话；

用测试事件调用发送事件接口，确认事件编码已注册生效、订阅完成、payload 结构符合注册内容；

在贵方业务系统中接入推送逻辑，事件发生时先完成会话映射，再推送事件。

对接方案概述

事件同步对接方案#

一、这套接口解决什么问题#

二、对接前置条件#

1. 注册事件编码#

2. 训练与订阅#

3. 鉴权#

4. 适用范围#

三、接口一：查询会话#

用途#

接口文档#

最佳实践：优先传企微明文 ID#

返回结果的理解#

四、接口二：发送事件#

用途#

接口文档#

五、响应判断与问题排查#

六、推荐对接顺序#

事件同步对接方案

一、这套接口解决什么问题

二、对接前置条件

1. 注册事件编码

2. 训练与订阅

3. 鉴权

4. 适用范围

三、接口一：查询会话

用途

接口文档

最佳实践：优先传企微明文 ID

返回结果的理解

四、接口二：发送事件

用途

接口文档

五、响应判断与问题排查

六、推荐对接顺序