智能对话
取消
中文
中文
EN
取消
  • 开放接口

    • # 接入智能对话

    接入之前，需要先在对话平台官网创建机器人，并在应用绑定中申请开放 API 的接入参数。 例如：

    APPID: Gg8HejYTkUsEIlG
Token: YV78Pyj1VvqdNGpMJ1pHic0bIBOWMv
AESKey: q1Os1ZMe0nG28KUEx9lg3HjK7V5QyXvi212fzsgDqgz

    参数说明：

    • APPID：和机器人一一对应，和 Token、AESKey 对应。
    • Token：用于签名，签名不通过的请求将拒绝响应。
    • AESKey：用于对 body 数据进行对称加解密，加解密算法为 AESCBC 算法。

    # 1. 安全性

    # 1.1 数据加密

    如果需要加密传输的接口，则使用 AESKey 进行对称加密。请求的 body 数据会解密后再处理，响应的数据也需要解密后，才可以得到下文的示例响应。 如果接口需要加密传输，将会特殊说明。

    具体算法细节可参考 第三方服务接口 中“加密”一栏的介绍。

    # 1.2 签名

    每一个请求都需要签名。签名需要使用上文申请的Token,具体的签名方法：

    sign = md5(Token + str(unix_timestamp) + nonce + md5(body))

    GET 请求的 body 为空

    md5 为小写的 hex 格式。

    具体字段下文有说明。

    例如：

    Token:YV78Pyj1VvqdNGpMJ1pHic0bIBOWMv
unix_timestamp:1711001766
nonce:abc
body:空
sign:fff8dae1356e7867ea98743439f0e9f8

    # 2. 公共参数

    # 2.1. 请求参数

    # header 参数

    几乎所有请求都应该携带这些 header。 X-APPID 仅在换取 X-OPENAI-TOKEN 的时候携带，后续都携带 X-OPENAI-TOKEN。X-OPENAI-TOKEN 仅 2h 有效，过期后应该更换新的。（X-APPID 和 X-OPENAI-TOKEN 二选一）

    字段名 类型 含义
    X-OPENAI-TOKEN string 开放接口接入的 Accesstoken，除了换 token 的接口都需要
    X-APPID string 开放接口接入的 appid,用于换 Accesstoken
    request_id string 请求唯一标识，可以随机生成，用于反馈问题，例如使用 UUID
    timestamp uint64 s 为单位的当前时间戳
    nonce string 随机字符串，建议长度在 10-32 位之间
    sign string 签名参数，校验请求来源合法性

    # 请求参数

    部分查询接口支持分页参数。

    字段名 类型 含义
    page int 分页参数，部分接口支持；第几页，从 0 开始
    size int 分页参数，部分接口支持；每页的数量，默认是 10

    # 2.2. 响应参数

    字段名 类型 含义
    request_id string 请求唯一标识，和 header 中的对应
    code int32 返回码
    0-正确
    else-有异常，错误详情可以参考 message 和 data 字段
    msg string 返回信息
    success-正确
    else-错误信息摘要
    data object 业务具体响应，详情请参考具体接口说明

    # 3. 换取 Accesstoken

    # 功能说明

    通过 appid，account 换取一个 2 小时有效的 换取 Accesstoken，用于后续的请求的身份校验，后面带到 header:X-OPENAI-TOKEN 中。

    # 请求 uri

    /v2/token

    # 请求类型

    POST

    # 请求参数

    # params

    字段名 类型 必填 描述
    account string 否 操作数据的管理员 ID，可以点击官网头像旁的箭头查看。如果不填，默认用超级管理员的身份。该字段主要用于记录操作日志。

    # 返回参数

    字段名 类型 必填 描述
    data.access_token string 是 访问令牌，默认有效期为 2 小时

    如果签名校验不通过，http status code 是 400。

    # 示例

    • 请求示例
    curl -X POST \
  https://openaiapi.weixin.qq.com/v2/token \
  -H 'X-APPID: Gg8HejYTkUsEIlG' \
  -H 'request_id:54ae04cf-5e95-44fd-ad3f-62e7b163836b' \
  -H 'timestamp:1711001766' \
  -H 'nonce:abc' \
  -H 'sign:通过sign=md5(Token+str(unix_timestamp)+nonce+md5(body))生成' \
  -H 'content-type: application/json' \
  -d '{
    "account":"fb2ab07ce06"
}'
    • 正确返回示例
    {
  "code": 0,
  "data": {
    "access_token": "MX6ddM5mN07ucVKy+Y-to7tKRufZ1YF05eb542d5170000001c"
  },
  "msg": "success",
  "request_id": "54ae04cf-5e95-44fd-ad3f-62e7b163836b"
}
    • 错误返回示例
    {
  "code": 110002,
  "msg": "参数错误，缺少必要参数，或参数不正确",
  "request_id": "54ae04cf-5e95-44fd-ad3f-62e7b163836b"
}

    # 4. 接口索引

    接口名 uri
    获取 Accesstoken /v2/token
    异步任务查询 /v2/async/fetch
    机器人导入/覆盖 /v2/bot/import/json
    机器人发布 /v2/bot/publish
    查询机器人发布进度 /v2/bot/effective_progress
    调用智能对话 /v2/bot/query

    # 5. 附录

    下载 postman 请求示例文件

    # 6. 常见问题

    1. 如何反馈 bug？

      提供请求的接口、request_id、问题描述、发生时间点等信息反馈给我们。