回调配置
回调让 IM 服务把应用内的变化推送到你的业务服务端（事件回调），并在用户发消息、加好友、加群之前询问你的服务端（同步回调），说明见回调概述。本页介绍如何在控制台中添加回调地址、选择事件、开启同步回调，以及查看投递记录和重新投递。
回调在应用详情的“回调”标签页中管理，下面有三个子标签页：
| 子标签页 | 内容 |
|---|---|
| 回调地址 | 添加、修改、验证、测试、暂停和删除回调地址；点击地址的名称打开详情，查看签名密钥、投递队列、请求记录和统计，批量重新投递 |
| 同步回调 | 开启和设置发消息前、发聊天室消息前、加好友前、加群前四种同步回调，测试和查看统计 |
| 事件目录 | 全部事件类型、说明和 data 的示例 |
谁可以操作
回调会把用户资料和消息内容发到你指定的地址，新增地址或订阅等于开通一条数据外发的通道，所以修改配置只开放给 owner 和 admin，其中改变“数据发到哪里、发哪些数据”的操作还要重新验证身份：
| 操作 | owner | admin | developer | 重新验证身份 |
|---|---|---|---|---|
| 查看回调地址、同步回调的设置、事件目录、投递队列、请求记录和统计 | ✓ | ✓ | ✓ | |
| URL 验证、测试发送、测试同步回调 | ✓ | ✓ | ✓ | |
| 暂停和恢复地址，重新投递 | ✓ | ✓ | ✓ | |
| 修改地址的名称、合并、超时、并发和速率，减少订阅的事件、收紧过滤条件 | ✓ | ✓ | ||
| 提前结束旧密钥的宽限期 | ✓ | ✓ | ||
| 新建和删除地址，修改 URL，增加订阅的事件，放宽过滤条件 | ✓ | ✓ | ✓ | |
| 轮换签名密钥 | ✓ | ✓ | ✓ | |
| 开启、关闭和设置同步回调 | ✓ | ✓ | ✓ |
developer 看不到“新建地址”“修改”“删除”“轮换”和同步回调的“设置”按钮。全部写操作都记入操作日志，日志中不记录签名密钥和事件内容。租户被暂停或处于注销冷静期时，“回调”页只能查看，不能修改，也不能验证、测试和重新投递。
新建回调地址
在“回调地址”中点击右上角的“新建地址”（每个应用最多 5 个地址，满 5 个时按钮不可用），填写：
| 字段 | 说明 |
|---|---|
| 名称 | 1 到 64 个字符，如“业务系统”“消息归档” |
| URL | 接收回调的地址，只允许 https 和公网域名，端口为 443 或 1024 到 65535，规则见地址的要求 |
| 订阅的事件 | 至少选择一种。按类别分组，每组的第一项“类别.*”订阅这一类的全部事件（包括以后新增的），见订阅事件 |
| 不回调服务端发起的操作 | 开启后，你的服务端通过 OpenAPI 和你在控制台的操作引起的事件不再发送，撤回消息除外，见过滤条件 |
| 删除用户时不回调连带的变化 | 开启后，删除用户连带解除的好友关系和退出的群不再逐条发送 |
| 消息的会话类型 | 消息事件接收单聊、群聊，还是都接收 |
| 接收群提示消息 | 消息抄送是否包括群提示，默认不包括 |
| 每批事件数 | 1 到 100，默认 1。大于 1 时一次请求合并多个事件，适合消息抄送等量大的事件 |
| 超时（毫秒） | 1000 到 10000，默认 5000 |
| 最大并发 | 1 到 50，默认 10 |
| 每秒请求数 | 1 到 1000，默认 100，不能超过应用的上限（输入框下方显示，默认 500，全部地址合计） |
点击“保存”，按提示重新验证身份。保存成功后：
- 弹出对话框显示这个地址的签名密钥（
cbs_开头），只显示这一次，请复制保存到接收端的配置中，然后点击“我已保存密钥”。忘记保存时可以轮换密钥； - 系统立即向 URL 发送一次 URL 验证，对话框中显示验证的结果。通过后地址的状态为“正常”，开始投递事件；没有通过的为“待验证”，不投递事件。
URL 验证和测试发送每个应用合计每分钟最多 20 次。额度用完时地址照常保存为“待验证”，对话框提示稍后在列表中点击“验证”。
先调通签名，再验证
接收端还没有准备好时也可以先保存地址：用“测试”发送一个事件，对照结果中的请求体调通签名校验，再点击“验证”。签名的校验方法和示例代码见验证回调请求。
回调地址列表
| 列 | 说明 |
|---|---|
| 名称 | 点击打开地址详情 |
| URL | 查询参数的值显示为 ***，见下文 |
| 订阅 | 订阅的事件数，鼠标悬停显示全部 |
| 状态 | 待验证、正常、已暂停、自动停用、平台停用，含义见地址的状态；鼠标悬停显示停用的原因。有同步回调绑定这个地址时另显示“同步回调”标签 |
| 健康 | “正常”，或“自 … 起失败”（鼠标悬停显示最近的错误和失败时间）；熔断中、积压的条数 |
| 操作 | 修改、验证、测试、暂停或恢复、删除 |
列表上方显示应用全部地址合计的每秒请求数上限，以及回调请求的出口 IP（平台配置了时），可以把这些 IP 加入接收端的防火墙白名单。
验证
点击“验证”，系统向地址发送一次 URL 验证，显示结果：成功或失败、失败的原因（如“连接失败”“非 2xx 状态码”“challenge 不正确”）、HTTP 状态码、耗时、对方的 IP 和响应的开头部分。“待验证”的地址验证通过后变为“正常”；其他状态的地址验证不改变状态，只用于检查接收端是否可用。
测试发送
点击“测试”，选择一种事件类型（不要求已订阅），系统用事件目录中的示例数据构造一个事件（test 为 true）立即发送，不写入投递队列。结果中除了验证结果中的各项，还有本次发出的完整请求体，便于调试签名。测试不要求地址已经通过验证，被平台停用的地址除外。
修改地址
点击“修改”，修改各项设置后保存。URL 留空表示不修改：列表中显示的 URL 已经把查询参数的值替换为 ***，修改 URL 时请填写完整的新 URL（查询参数的值为 *** 时不能保存）。
- 需要重新验证身份：修改 URL、增加订阅的事件（把
group.*换成group.created不算增加，反过来算），或放宽过滤条件（关闭“不回调服务端发起的操作”“删除用户时不回调连带的变化”，开启“接收群提示消息”，增加消息的会话类型）时。其他修改不需要。 - 修改 URL 后：地址回到“待验证”，系统立即对新的 URL 发送一次验证，显示结果；验证通过之前不投递事件，绑定在这个地址上的同步回调也按失败处理（失败策略为“拒绝”的会拒绝相应的操作）。请先把同步回调改绑到其他地址，或暂时改为“放行”。
- 修改订阅和过滤条件只影响之后的事件，已经排队的照常发送。
- 两个人同时修改同一个地址时，后保存的会提示数据已被修改，刷新后重新修改即可。
暂停与恢复
接收端停机维护时，可以点击“暂停”：事件照常排队、不发送，恢复后继续发送。每个事件从排队起 24 小时仍未发出的转为投递失败（从排队时起算，不是从暂停时起算），可以在 7 天内重新投递。暂停不影响同步回调。
点击“恢复”：
- “已暂停”的地址直接恢复为“正常”；
- “自动停用”的地址（持续失败 24 小时后被系统停用，见持续失败与自动停用）先发送一次 URL 验证，通过后恢复为“正常”，没有通过时保持停用并显示验证的结果。恢复后，再批量重新投递停用前投递失败的事件；停用期间发生的事件没有排队，不会补发。
“待验证”的地址不能恢复，请点击“验证”。
删除地址
owner 和 admin 点击“删除”并确认（需要重新验证身份）。删除后立即停止投递，绑定这个地址的同步回调同时关闭，排队中的事件和请求记录随后删除，不能恢复。
被平台停用的地址
地址被平台停用时（通常是地址指向了不属于你的第三方），状态为“平台停用”，详情顶部显示停用的原因。停用期间不投递事件，绑定它的同步回调按失败处理；你不能修改它的 URL、删除、验证、测试和重新投递，它仍计入 5 个地址的上限。如有异议请联系我们，由平台恢复。
地址详情
点击地址的名称打开详情，顶部是地址的设置和健康状况：
| 项目 | 说明 |
|---|---|
| 状态、地址 ID | 地址 ID 即请求头 X-IM-Endpoint-Id |
| 每批 / 超时、并发 / 每秒 | 当前的设置；平台调低了应用的上限时，实际生效的每秒请求数会更小，并注明“受应用上限限制” |
| 最近成功、最近失败 | 最近一次事件回调成功、失败的时间和失败的原因 |
| 持续失败 | 从最近一次成功之后开始失败的时间；持续 1 小时会通知 owner 和 admin，持续 24 小时自动停用 |
| 积压 | 待投递的事件数和上限（默认 50 万），以及最早一条的排队时间，每 30 秒左右统计一次 |
| 熔断 | 正常、熔断中、试探中，见重试 |
| 验证时间 | 最近一次通过 URL 验证的时间 |
| 签名密钥 | 当前密钥的版本和前 8 个字符，见下文 |
下方有四个标签页：投递队列、请求记录、统计、批量重新投递。
签名密钥
详情中只显示密钥的前 8 个字符（如 cbs_Le8E…），用于辨认，完整的密钥只在新建地址和轮换时显示一次。
- 轮换：
owner和admin点击“轮换”，填写旧密钥的宽限期（1 到 168 小时，默认 24 小时），确认并重新验证身份后，对话框显示新密钥（只显示这一次）。新密钥立即生效；宽限期内每个请求同时带新旧两个签名，接收端用哪一个都能校验通过，详情中显示“旧密钥 … 的宽限期至 …”。宽限期还没结束时不能再次轮换。 - 提前结束宽限期：接收端都换成新密钥后，点击“提前结束宽限期”，之后只用新密钥签名，还在用旧密钥的接收端会校验失败。不需要重新验证身份。
不停机更换密钥的步骤见轮换密钥。密钥不会自动过期。
投递队列
按状态查看这个地址的投递：
| 状态 | 内容 |
|---|---|
| 待投递 | 正在排队或等待重试的事件，按下次发送的时间排列 |
| 失败（默认显示） | 24 小时内没有投递成功的事件，保留 7 天，可以重新投递 |
| 已投递 | 投递成功的事件，保留 1 小时 |
可以按事件类型筛选，或在“按事件 ID 查询”中输入事件 ID（如接收端日志中的 events[].id）查找这个事件对这个地址的投递。列表显示事件类型、事件 ID、状态、发送次数、最近的错误和状态码、下次发送或完成的时间、排队时间。
- 详情：查看事件的发生时间、发送次数、最近一次请求的 ID 和事件的
data。消息类事件（消息抄送、消息编辑、聊天室的消息抄送）不显示body和ext；投递成功后不保留内容。 - 重新投递：失败的事件可以点击“重新投递”，事件回到待投递，发送次数清零，24 小时的期限重新计算。地址必须是“正常”或“已暂停”（暂停时排队，恢复后发送）。
请求记录
每次向这个地址发出的请求，保留 7 天，可以按结果（成功、失败）和类型（事件、同步回调、URL 验证、测试）筛选：
| 列 | 说明 |
|---|---|
| 时间、类型 | 重新投递的请求另有“重新投递”标签 |
| 名称 | 事件类型或同步回调的类型；合并发送的注明事件数 |
| 第几次 | 事件的第几次发送 |
| 结果 | 成功（同步回调另显示结果，如 allow、reject、modify、fallback_allow），或失败的原因 |
| HTTP、耗时、对方 IP | 对方返回的状态码、请求的耗时和实际连接的 IP |
展开一行可以看到请求 ID（即请求头 X-IM-Request-Id）、包含的事件 ID、错误的说明、对方响应的开头部分和请求体的大小。请求记录不保存事件的内容。URL 验证、测试、重新投递和失败的请求基本全部记录，成功的请求按抽样记录，完整的数量见统计。
失败的原因：
| 原因 | 说明 |
|---|---|
| 域名解析失败 | URL 中的域名无法解析 |
| 解析到了非公网地址或被出口代理拒绝 | 实际要连接的 IP 不是公网地址，连接前已拒绝 |
| 连接失败 | 连接被拒绝、不可达或连接超时 |
| TLS 握手失败 | 证书无效、过期或与域名不符 |
| 超时 | 在超时时间之内没有读完响应 |
| 非 2xx 状态码 | 对方返回了 4xx、5xx 等，括号中为状态码 |
| 返回了跳转（不跟随） | 对方返回了 3xx |
| 响应过大 | 同步回调、URL 验证的响应超过上限 |
| 响应无效 | 同步回调返回了 2xx，但响应体不符合要求，见同步回调的响应 |
| challenge 不正确 | URL 验证的响应中没有正确的 challenge |
统计
最近 24 小时或 7 天的统计，保留 90 天：
- 按事件类型：每种事件的排队数、投递成功数、失败数、丢弃数（积压达到上限，或在线状态、聊天室的事件因缓冲已满被丢弃）、跳过数（地址不是正常或暂停状态，或应用不可用时没有生成投递）；
- 按小时：请求数、失败数、超时数、熔断时跳过的次数、平均和最大耗时、投递成功的事件数、事件从发生到投递成功的平均和最大延迟。
批量重新投递
接收端故障修复后，可以按失败的时间批量重新投递：选择失败时间的范围（相差不超过 7 天），可以只选几种事件类型，点击“重新投递”。每次最多处理 1 万个事件，提示“还有更多”时再提交一次。地址必须是“正常”或“已暂停”，“自动停用”的地址请先恢复。
同步回调
“同步回调”中列出四种同步回调，说明见同步回调：
| 列 | 说明 |
|---|---|
| 同步回调 | 发消息前（message.before_send）、发聊天室消息前（chatroom.before_send）、加好友前（friend.before_add）、加群前（group.before_join） |
| 状态 | 已开启或未开启。开启了、但绑定的地址处于“待验证”或“平台停用”时另显示“地址不可用”：这时不发请求，按失败策略处理，失败策略为“拒绝”的会拒绝全部相应的操作 |
| 绑定地址 | 调用的回调地址 |
| 等待 | 等待响应的时间 |
| 失败时 | 放行或拒绝 |
| 操作 | 设置、测试、统计 |
设置同步回调
owner 和 admin 点击“设置”，保存时需要重新验证身份：
| 字段 | 说明 |
|---|---|
| 开启 | 开启或关闭这种同步回调。关闭时保留其他设置 |
| 调用的地址 | 开启时必须选择。“待验证”和“平台停用”的地址不能选择 |
| 等待时间（毫秒） | 100 到 3000，默认 1000。实际等待的时间不超过操作方剩余的时间：消息的全部发送前检查合计 3 秒，聊天室消息合计 500 毫秒 |
| 超时、出错或响应无效时 | 放行（默认）或拒绝，见失败时的处理 |
| 调用条件 | 因类型而不同：发消息前为发送入口、会话类型、消息类型、是否包括只推在线的消息、是否包括编辑；发聊天室消息前为发送入口、消息类型、优先级；加好友前为阶段（发送申请、同意申请）；加群前为入群方式和群类型。不满足条件的操作直接放行。各项见同步回调 |
保存后通常 1 秒内生效。开启“失败时拒绝”之前，请确认接收端稳定：接收端故障时，全应用的相应操作都会失败。
测试和统计
- 测试：用示例数据向绑定的地址发送一次同步回调请求（不要求地址已通过验证），显示是否成功、你的服务端的决定（如
allow），或响应无效的原因。没有绑定地址时不能测试。 - 统计：最近 24 小时每小时的调用次数，放行、拒绝、改写和失败的次数，超时、时间不足、熔断、地址不可用而没有发出请求的次数，失败后按策略放行和拒绝的次数，以及平均耗时。
事件目录
“事件目录”列出全部可以订阅的事件类型、所属类别和说明，可以按类别筛选，展开一行查看 data 的示例，即测试发送时使用的数据。各事件的字段说明见事件回调。
订阅独立频道事件
频道事件位于音视频类别，类型前缀为 rtc_channel，完整列表见频道事件。选择 rtc_channel.* 订阅九类事件；原 rtc.* 不包含它们。配置变化内部通知不属于租户回调。新增订阅仍遵循本页重新验证身份的规则，接收端需处理重复与乱序。