客服开通接口

客服 V1 API（session/create、agent/assign、agent/status、agent/message/send）都围绕一个 agentId 工作。agentId 不是平台预置的，需要先通过本节的开通接口把「蓝答账号」绑定为应用下的客服。

只要请求满足下列任一种鉴权方式，任何接入方都可以调用。

鉴权方式

/api/open/console/v1/agents/bind 与 /api/open/console/v1/tenants/{tenantId}/app 这两个开通端点支持三种鉴权，满足其一即可：

方式	请求头	租户上下文来源
应用签名 V2（推荐服务端对服务端）	`X-Open-App-Id`、`X-Open-Credential-Id`、`X-Open-Timestamp`、`X-Open-Nonce`、`X-Open-Signature`	自动取自该应用所属租户
开发者 JWT	`Authorization: Bearer <accessToken>` + `X-Open-Tenant-Id`	`X-Open-Tenant-Id`
管理令牌 admin-token	`Authorization: Bearer <admin-token>` + `X-Open-Tenant-Id`	`X-Open-Tenant-Id`（可代理任意租户）

注意：

用签名 V2 时，请求体里的 tenantId 必须与该应用所属租户一致，否则返回租户上下文错误。此路径要求应用已 ACTIVE：agents/bind 与 tenants/{tenantId}/app 两个端点都只在应用生命周期为 ACTIVE 时可用，非 ACTIVE 时开通失败。
用 JWT / admin-token 时，X-Open-Tenant-Id 实际上不可省略：缺失时无法建立租户上下文，接口会以错误响应拒绝。
admin-token 仅对上述两个开通端点放行，其余控制台端点仍要求开发者 JWT。

开通客服

POST /api/open/console/v1/agents/bind
Content-Type: application/json

{
  "tenantId": "88",
  "appId": "app_43e19f98e5584c51925d08fc",
  "agentId": "agent_001",
  "agentName": "客服小蓝",
  "imUsername": "lanlan",
  "limUserId": "lanlan"
}

字段	类型	必填	说明
`tenantId`	string	✅	企业租户 ID，必须与当前租户上下文一致。在控制台应用管理列表页顶部「当前企业」处查看，见应用管理 → 获取接入凭证与租户 ID
`appId`	string	✅	应用 ID
`agentId`	string	✅	由接入方自定义的应用内客服标识，同一应用内唯一
`agentName`	string	—	客服显示名
`imUsername`	string	—	该客服已绑定过的蓝答账号名；仅在客服人员已有蓝答账号时传，见什么时候传 imUsername / limUserId
`limUserId`	string	—	该客服已存在的蓝答用户标识。传了就复用该用户，不再新建

响应：

{"code": "000000", "message": "成功", "value": {"imUsername": "lanlan", "duplicate": false}, "reqNo": null}

行为说明

幂等：若 (appId, agentId) 已开通且已有 imUsername，直接返回原 imUsername 并置 duplicate: true，不会重复开通。
要求应用已审核通过：应用生命周期不是 ACTIVE 时开通失败。
imUsername 派生规则：未传或超过 32 字符时，派生为 "ag" + agentId（超长截断）。后续用 agent/message/send 发消息时，agentUsername 一律传响应里返回的 imUsername，而不是 agentId。
自动建立好友关系：开通时会补齐该客服与租户内存量访客的双向好友关系，保证客服能直接回复已有访客。
limUserId 与 imUsername 的区别：两者都用于「复用已存在的蓝答账号」，指向同一个蓝答用户（LIM username）——limUserId 传蓝答用户标识，imUsername 传账号名。

什么时候传 `imUsername` / `limUserId`

这两个字段只有一种使用场景：接入方的客服人员之前已经在蓝答（LIM）侧绑定了账号，你希望这次开通直接复用那个账号。

情况	怎么传	结果
客服人员已绑定过蓝答账号	传该账号：`imUsername` 传账号名，或 `limUserId` 传已存在的蓝答用户标识	复用已有蓝答用户，不新建
客服人员从未绑定过蓝答账号	两个都不传	平台新建蓝答用户，账号名按 `agentId` 派生为 `"ag" + agentId`

开通成功后，接入方需要在自己系统里保存「自家客服账号 ↔ 平台返回的 imUsername」的对应关系。平台没有查询客服账号的接口（见下），映射丢失后只能拿同一个 agentId 再调一次本接口幂等取回。

查询应用审核状态

该端点同样要求应用已 ACTIVE（与 agents/bind 一致，见鉴权方式）。

GET /api/open/console/v1/tenants/{tenantId}/app?appId=app_43e19f98e5584c51925d08fc

响应 value 为 {appId, auditStatus, rejectReason}，auditStatus 映射：

`auditStatus`	含义
`0`	未配置，或不存在，或处于非审核态（`DRAFT`/`SUSPENDED`/`DELETED`）
`1`	待审核（`PENDING_REVIEW`）
`2`	已通过（`ACTIVE`）
`3`	已驳回（`REJECTED`），原因见 `rejectReason`

错误响应

控制台接口不适用开放 API 的 ApiResult 契约。开通端点失败时返回 Spring 默认错误体：

{
  "timestamp": "2026-09-15 14:13:55",
  "status": 500,
  "error": "Internal Server Error",
  "message": "400402:应用未审核通过",
  "path": "/api/open/console/v1/agents/bind"
}

请从 message 中取原因（agents/bind 会带内部码前缀）：

`message` 前缀	含义
`400402:`	应用未审核通过（非 `ACTIVE`）
`400404:`	应用不存在，或指定的 `limUserId` 对应的蓝答用户不存在
`tenant context required`	缺少或与请求体不一致的租户上下文

开通之后

开通成功并拿到 imUsername 后：

agentId 可用于 session/create、agent/assign、agent/status；
客服主动给访客发消息用 POST /api/open/v1/agent/message/send，其中 agentUsername 传蓝答账号（即本接口返回的 imUsername），不是 agentId。

开放平台没有公开的客服列表接口。请在调用方保存「自家客服账号 ↔ agentId ↔ imUsername」的映射，不要试图从平台反查。

相关：应用生命周期、客服开放 API。

鉴权方式​

开通客服​

行为说明​

什么时候传 imUsername / limUserId​

查询应用审核状态​

错误响应​

开通之后​