跳到主要内容

快速开始

本指南以服务端应用为例，完成从创建应用到调用 API 的最小闭环。

1. 准备账号和企业​

在蓝答客户端创建或加入企业组织，然后打开开发者控制台。开放平台复用蓝答企业身份，不需要再次创建企业。

测试环境的控制台地址为 https://im-open-test.lanchr.com，正式 / 测试两套地址的完整对照见鉴权与签名 → 服务地址。

2. 创建应用​

在控制台创建应用并选择能力类型。创建成功后，credentialId 和 appSecret 只展示一次：

  • 只把 Secret 写入服务端密钥管理系统；
  • 不要写入前端、日志、截图或 Git 仓库；
  • 轮换凭证后旧凭证进入失效流程，但有 24 小时宽限期，宽限期内旧凭证仍可用；请在宽限期内完成切换。

签名要用到的 appId、credentialId、appSecret 和 tenantId 分别去控制台哪里取，见应用管理 → 获取接入凭证与租户 ID。

3. 配置权限和事件​

按最小权限申请 Scope。按应用类型选择：

机器人应用最小权限

bot.installation.read
bot.message.send
bot.message.reply
event.bot.message

客服应用最小权限

customer.visitor.manage
customer.session.manage
customer.message.send
customer.message.read
customer.agent.read

缺少 Scope 的调用会返回 403，code 为 400007，message 为「所需的开放平台Scope未被授权」。完整的「接口 ↔ 必需 Scope」映射表见错误与限制 → Scope 与 403，请以该表为准，不要凭猜测申请。

如果需要接收事件，请填写公网 HTTPS Webhook 地址并完成验证。回调服务必须能够校验签名、快速返回 2xx，并使用 eventId 去重。Webhook 签名密钥（Webhook Secret）在保存事件订阅时由平台一次性返回，获取方式见 Webhook 事件。

4. 发布应用​

提交审核后应用进入 PENDING_REVIEW；通过后进入 ACTIVE，此时才能调用开放 API。DRAFT、PENDING_REVIEW、REJECTED、SUSPENDED 状态的应用会被拒绝，返回 403 + 400005。完整状态机见应用生命周期。

5. 获取接收方 ID（机器人）​

机器人的 receiveId 是目标会话的 ID，需要先从平台查询，不能自己编造。用同一个应用凭证调用安装关系接口：

GET /api/open/v2/bot/installations?targetType=USER&status=ACTIVE
X-Open-App-Id: <app-id>
X-Open-Credential-Id: <credential-id>
X-Open-Timestamp: <timestamp-ms>
X-Open-Nonce: <unique-nonce>
X-Open-Signature: <hmac-sha256>

响应中的 items[].targetId 即为 receiveId，items[].targetType 为 USER 或 GROUP：

{
  "code": "000000",
  "message": "成功",
  "value": {
    "items": [
      {"targetType": "GROUP", "targetId": "1024", "targetName": "项目群", "status": "ACTIVE"}
    ],
    "total": 1, "page": 1, "pageSize": 100
  }
}
  • targetType=GROUP → 发送时 receiveIdType 用 group_id，receiveId 用 targetId（纯数字）。
  • targetType=USER → 发送时 receiveIdType 用 user_id，receiveId 用 targetId（用户账号）。

只有已安装且状态为 ACTIVE 的目标才能接收消息，未安装时发送会返回 403 + 400008「机器人未安装到此目标」。安装由企业成员在蓝答客户端完成，或由开发者在控制台「机器人 → 安装范围」中为用户安装。

6. 发出第一条请求​

以机器人向已安装的群发送文本为例。请求需要按签名 V2计算 X-Open-Signature；注意这里使用应用凭证签名，不是浏览器 Token：

curl -X POST 'https://im.lanchr.com/api/open/v2/bot/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-Open-App-Id: <app-id>' \
  -H 'X-Open-Credential-Id: <credential-id>' \
  -H 'X-Open-Timestamp: <timestamp-ms>' \
  -H 'X-Open-Nonce: <unique-nonce>' \
  -H 'X-Open-Signature: <hmac-sha256>' \
  --data-binary '{
    "receiveIdType": "group_id",
    "receiveId": "1024",
    "msgType": "text",
    "content": {"text": "构建完成"},
    "clientMessageId": "build-text-001"
  }'

Content-Type: application/json 与 --data-binary 都必须显式写出。缺少 Content-Type 会返回 415 + 415001（Content-Type 不受支持）——注意响应 message 里那份「支持」清单不可信（会把刚判为不支持的类型也列进去），只看「不支持的 Type」前半句即可，详见鉴权与签名。

成功响应：

{
  "code": "000000",
  "message": "成功",
  "value": {"messageId": 8229, "msgSeq": 8703555237400514685, "clientMessageId": "build-text-001", "duplicate": false},
  "reqNo": "e81fea0ebfa9453e9cbca71a232c1fd5"
}

用相同 clientMessageId 重发不会产生新消息，duplicate 会变为 true 并返回原 messageId。

请求和响应字段请以 机器人 API V2 为准。