首页 / 开放平台 / 开发帮助 / 开发指南总览

常见问题

开发帮助 更新于 2026-09-21 阅读 9

阅读指引：本篇汇总接入各阶段的常见问题与排查思路。定位到问题类别后，可按给出的指引跳到对应文档核对细节。

接入准备

  1. 如何获得开发者身份并创建应用？

    答：当前不提供自助创建应用的 OpenAPI。请向平台管理员提交应用资料（app_identifier、名称图标描述、访问地址、可信域名、oauth_callback_uri），由管理员完成创建、授权与发布，再通过安全渠道交付 app_key、app_secret、sign_key。详见《快速开始》。

  2. 第三方应用系统接入开放平台，等于拿到了应用管理权限吗？

    答：不等于。应用的 Scope、发布范围、可信域名与回调地址都由管理员配置；需要调整时联系管理员。

认证与授权

  1. 换取用户 Token 时提示 code 非法（invalid_grant）？

    答：authorization code 5 分钟内有效且只能使用一次，重复使用或过期都会失败；另外换 Token 时提交的 redirect_uri 必须与申请 code 时完全一致。

  2. Token 报 170104 / 170209 怎么处理？

    答：分别表示应用 Token、用户 Token 无效或过期。按 expires_in 缓存并在到期前刷新；收到失效错误时重新认证，不要循环重试旧 Token。权限变更后既有 Token 会被撤销，也按重新认证处理。

  3. H5 应用每次打开都要走一遍 OAuth 吗？

    答：不需要。建议应用在获取用户身份后用 cookie + session 缓存应用内登录状态（3～7 天），过期后再重新授权；session 建议放 Redis 等共享存储，服务多实例时必须共享。

  4. 用户资料接口能不能查指定用户？

    答：不能。GET /user/profile 只返回 Token 对应的当前用户，不接收用户参数；其他用户信息请通过组织目录接口（需 contact:organization:read）在发布范围内读取。

消息与素材

  1. 怎么向一群人发通知？

    答：按目标粒度选择：指定用户用 recipient.type=user（最多 100 个）；按部门用 org_node（覆盖部门及全部后代）；全租户用 all（需发布范围显式含 user:0 与 message:send:all）。同一请求只能选一种目标类型。

  2. 为什么向群发消息失败？

    答：检查三点：应用具备 group:app；群主或管理员已把应用添加进该群且关系 active；ids 只包含一个群 ID。应用被移出群或下架后原关系失效，重新添加后也不会自动恢复。

  3. 上传的素材在消息里报无效？

    答：素材消息的 media_id 必须属于当前应用、类型与消息类型完全一致（如 image 消息只能引用 type=image 上传的素材）且已处理完成。当前消息发送不支持 video。

  4. 消息重发会不会造成用户收到重复消息？

    答：只要重试时复用原 request_id 并保持目标与内容完全一致，平台会按幂等处理；不同消息不要复用同一个 request_id。

Webhook 与事件

  1. Webhook 验证一直 failed？

    答：依次检查：是否原样返回了 challenge（不能解码或改写）；响应 code 是否为数字 0；响应是否用 sign_key 签名且 body 未超过 1024 字节；HTTP 状态是否 2xx。

  2. 验签总是失败？

    答：最常见原因是对 JSON 重新序列化后再验签。必须使用未经解析的原始请求体字节计算；同时确认使用的是当前 sign_key（重置后旧密钥立即失效）、时间偏差不超过 5 分钟。

  3. 同一条消息被处理了多次？

    答：平台对失败投递会重试，同一事件的 event_id 不变。应用必须按 event_id 幂等（如以应用标识 + event_id 建唯一键），重复事件直接返回 2xx；耗时业务异步执行，5 秒内响应。

同步

  1. 组织同步过程中返回 409 / 170703？

    答：同步期间目录或发布范围又发生了变化。丢弃整个临时批次，重新从 sync-state 开始，不要修补半成品数据。

  2. 群成员增量读取的游标失效？

    答：sign_key 重置、群关系移除或平台同步重置都会使游标失效。此时清空本地游标，用 groups/changes 重新全量拉取。游标是不透明字符串，不要解析或拼装。

客户端 JSSDK

  1. config 报签名或参数错误（CONFIG_INVALID / INVALID_SIGNATURE）？

    答：确认签名在应用后端用当前 jsapi_ticket 计算；签名字符串字段名与顺序严格按文档构造；页面 URL 与调用 config 的 URL 完全一致（去 # 及其后部分，保留 query 原顺序）；timestamp 为服务器当前毫秒（允许前后各 5 分钟）；nonce 不复用。

  2. openChat 没有任何反应？

    答：openChat 是受保护能力，需要：config 成功且 jsApiList 包含 openChat、管理员已授予 chat:conversation:open、由用户本次点击直接触发（不能放在定时器或页面加载里）、当前用户有权访问目标会话。逐项核对，错误码可参考《JSSDK 快速开始》的统一错误表。

  3. 从工作台打开应用时 getCurrentGroupId 返回空字符串？

    答：空字符串是成功结果，表示应用不是从群入口打开；从群会话入口打开时才返回群 ID。业务上应把空值视为「无群上下文」而非错误。

限流与错误

  1. 返回 170108 是什么意思？

    答：请求频率超限。所有接口共享来源 IP 每分钟 300 次的全局限制，发送类接口另有每应用 + 来源 IP 每分钟 60 次的专用限额；按对应窗口退避后重试。素材上传的专用限流返回 HTTP 429、170507。

  2. HTTP 200 但业务没成功？

    答：多数接口业务判断以响应 code 为准（200 才是成功），HTTP 200 不一定代表成功；限流、部分失败（如批量发送中的无效目标）都会通过业务码和明细字段返回。完整业务码表见《Scope 映射与错误处理》。