应用生命周期

一个应用从创建到调用 API 通常经过以下阶段：

DRAFT → PENDING_REVIEW → ACTIVE
                       ↘ REJECTED → PENDING_REVIEW → ACTIVE
ACTIVE → SUSPENDED → ACTIVE
任意状态 → DELETED

应用状态

状态	含义	能否调用开放 API
DRAFT	草稿，创建后的初始状态，可继续编辑	❌
PENDING_REVIEW	已提交审核，等待平台处理	❌
ACTIVE	审核通过，已发布	✅
REJECTED	审核未通过，按原因修改后可重新提交	❌
SUSPENDED	已停用（风险处置或管理员操作）	❌
DELETED	已删除	❌

提交审核后状态由 DRAFT 变为 PENDING_REVIEW（不是 SUBMITTED）。应用不是 ACTIVE 时，任何开放 API 调用都会返回 403 + 400005。

应用类型

创建应用时选择的 appType 决定可用的能力域。有效取值为：

appType	能力
GENERAL	通用应用（默认），可使用客服 V1 能力
BOT	应用机器人，可用机器人 V2 能力
MINIAPP	小程序商城，可用小程序 V2 运行时能力
CUSTOMER_SERVICE	客服应用，客服工作台场景

appType 决定能申请哪些 Scope、能调用哪些接口。例如 BOT 类型才能调用机器人 V2 接口；用其他类型调用会因缺少对应 Scope 而返回 403 + 400007。

创建和凭证

应用创建后处于 DRAFT，同时生成初始凭证。凭证 Secret 只在创建或轮换时展示一次。轮换凭证前，应先让服务端支持新旧凭证的短暂切换窗口。轮换后旧凭证进入失效流程，但有 24 小时宽限期：宽限期内新旧两套凭证都能通过校验，宽限期结束后用旧凭证签名的请求返回 401 + 400001。

Scope

Scope 是应用可以使用的最小权限单位。Scope 缺失时，即使签名正确也会返回 403 + 400007。建议按业务能力申请，完整的「接口 ↔ 必需 Scope」映射见错误与限制。

客服应用开通

客服 V1 API 都围绕 agentId 工作，而 agentId 不是平台预置的：需要先调用控制台开通接口 POST /api/open/console/v1/agents/bind，把「蓝答账号」绑定为应用下的客服。该接口不是某一接入方专用，任何满足签名 V2 / 开发者 JWT / admin-token 任一种鉴权的调用方都可使用。

完整字段、auditStatus 查询、幂等与 imUsername 派生规则、错误响应格式见客服开通接口。

绑定后：

• agentId 用于 session/create、agent/assign、agent/status。
• agentId 是应用内自定义的字符串，不是平台全局 ID；session/create 不会校验其是否存在，只有 agent/status 会返回 exists 判定。
• 开放平台目前没有公开的 agentId 列表接口，请在自己侧保存 agentId ↔ imUsername 的映射关系。

事件订阅

每个事件订阅包含事件类型、HTTPS 回调地址、订阅状态和各自的 Webhook Secret。保存订阅时会一次性返回 Webhook Secret；先执行地址验证，再提交应用审核。回调失败由平台异步重试，投递详情可在控制台查看。

发布与停用

只有 ACTIVE 应用可以调用开放 API。停用会同时影响 V1 和 V2 请求；恢复前请先检查凭证、Scope、Webhook 投递失败和审计日志。