服务开通

服务开通控制应用级能力开关：关闭后相关 Open API 与客户端能力返回 1021 SERVICE_NOT_ACTIVATED。自托管版没有“购买/开通订单”，这里的开关就是唯一事实源；部分能力（如敏感词过滤）即使关闭管理开关也仍生效，详见下表。

概念​

ServiceKey控制的能力关闭后的行为
private_chat单聊消息发布（message.private.publish、状态消息）上述发布接口 1021；好友/资料等接口不在此开关门禁内
group群组创建/成员/消息/状态消息群相关写操作与群消息发布 1021
supergroup超级群与频道/用户组super 群与 supergroup.* 接口 1021
chatroom聊天室创建/加入/消息/治理聊天室接口与聊天室消息发布 1021；控制台仍可看历史房间
system_notification系统通知发布系统通知发布 1021
callbacks回调事件投递与配置事件不入队；回调类 Open API 1021；控制台测试投递 1024
message_routing消息路由标记（预留）当前服务端没有读取该开关，未强制；路由由服务/回调/推送配置共同决定
sensitive_words敏感词管理接口门禁6 个词表管理接口 1021；已配置词表的过滤仍生效
  • 读写接口：GET/POST /api/admin/apps/{appkey}/services；写入是整体覆盖 services 映射，未传的键会回到默认关闭。
  • 控制台「服务与 API 配置」页与「功能配置」页读写同一份状态，不存在第二份开关。
  • 配额（群/聊天室成员上限、消息频率）也随本接口的 quotas 一起保存，见「配额」。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#services（tab #services：服务开通）。
  • 请求头 X-Admin-Secret 与服务端 IM_ADMIN_SECRET 一致（本地默认 dev-admin）。
  • 已在控制台选中应用；带 {appkey} 的接口都按应用隔离。
  • 自托管版无购买、计费、套餐、续费与发票流程（不适用项）；本页只覆盖配置、查询与治理接口。

步骤​

  1. 读取当前开通项

    先 GET，保存现有映射，避免整体覆盖时误关其它能力。

  2. 按需开启

    提交完整 services 映射；只改需要变更的键，其余保持原值。

  3. 验证业务接口

    调用对应 Open API；关闭时应返回 1021，开启后恢复正常。

  4. 与功能开关对齐
    features 页的 6 个开关映射到本页的 services，改任意一侧都会写穿同一状态。

参数表​

操作方法与路径请求体
读取GET /api/admin/apps/{appkey}/services—
整体更新POST /api/admin/apps/{appkey}/services{services:{ServiceKey:bool},quotas?}
功能开关映射GET /api/admin/apps/{appkey}/features—（含 mapping 说明）

示例​

开启聊天室并关闭回调​

Shell
# 先读，保留其它键
curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/services" \
  -H 'X-Admin-Secret: dev-admin'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/services" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"services":{"private_chat":true,"group":true,"supergroup":false,"chatroom":true,"system_notification":true,"callbacks":false,"message_routing":true,"sensitive_words":true}}'

常见问题​

关闭 sensitive_words 后敏感词还生效吗？​

生效。该开关只门禁词表管理接口；已保存的词表仍参与发送时过滤。

关闭 callbacks 会丢历史投递吗？​

不会删除历史日志，但新事件不再入队；重新开启后只投递新事件。

为什么开启后仍返回 1021？​

确认改的是当前 appkey，且提交的是完整映射；整体覆盖时漏传的键会被置为关闭。

自托管需要“购买服务”吗？​

不需要。没有订单、计费或有效期；开关即能力边界。

相关链接​