# 接入智能对话

接入之前，需要先在[对话平台官网](https://chatbot.weixin.qq.com/)创建机器人，并在应用绑定中申请开放 API 的接入参数。
例如：

```
APPID: Gg8HejYTkUsEIlG
Token: YV78Pyj1VvqdNGpMJ1pHic0bIBOWMv
AESKey: q1Os1ZMe0nG28KUEx9lg3HjK7V5QyXvi212fzsgDqgz
```

参数说明：

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

## 1. 安全性

### 1.1 数据加密

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

具体算法细节可参考 [第三方服务接口](../thirdapi/thirdapi#%E5%8A%A0%E5%AF%86) 中“加密”一栏的介绍。

### 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。

### 示例

- 请求示例

```bash
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"
}'
```

- 正确返回示例

```json
{
  "code": 0,
  "data": {
    "access_token": "MX6ddM5mN07ucVKy+Y-to7tKRufZ1YF05eb542d5170000001c"
  },
  "msg": "success",
  "request_id": "54ae04cf-5e95-44fd-ad3f-62e7b163836b"
}
```

- 错误返回示例

```json
{
  "code": 110002,
  "msg": "参数错误，缺少必要参数，或参数不正确",
  "request_id": "54ae04cf-5e95-44fd-ad3f-62e7b163836b"
}
```

## 4. 接口索引

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

## 5. 附录

[下载 postman 请求示例文件](https://xiaoweidevice-75050.gzc.vod.tencent-cloud.com/doc/chatbot_open_api.postman_collection.json)

## 6. 常见问题

1. 如何反馈 bug？

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