# 调用智能对话

## 功能说明

调用机器人的智能对话功能

## 请求 uri

`/v2/bot/query`

## 请求类型

`POST`

## 请求参数

### params

| 字段名                   | 类型                | 含义                                                                                                        |
| ------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `query`                  | string              | 用户发送的消息                                                                                              |
| `env`                    | string              | 默认是 online, debug 是测试环境, online 是线上环境                                                          |
| `first_priority_skills`  | Array<string> | 限定技能命中范围 比如：["技能 1"]，只匹配命中“技能 1”中的所有问答内容                                       |
| `second_priority_skills` | Array<string> | 限定技能命中范围 比如：["技能 2"]，只匹配命中“技能 2”中的所有问答内容,比 first_priority_skills 命中优先级低 |
| `user_name`              | string              | 用户昵称                                                                                                    |
| `avatar`                 | string              | 用户头像                                                                                                    |
| `userid`                 | string              | 用户 ID(可以是任何值)                                                                                       |

## 返回参数

### data

| 字段名        | 类型                    | 含义                                                                                |
| ------------- | ----------------------- | ----------------------------------------------------------------------------------- |
| `answer`      | string                  | 命中的回答                                                                          |
| `answer_type` | string                  | 回答的类型                                                                          |
| `skill_name`  | string                  | 技能名                                                                              |
| `intent_name` | string                  | 意图名                                                                              |
| `msg_id`      | string                  | 消息 id                                                                             |
| `options`     | Array<Option>     | 推荐问题列表 (有推荐时才出现该字段)                                                 |
| `status`      | string                  | 机器人回复的状态, 可能的数值：FAQ、NOMATCH、CONTEXT_FAQ、GENERAL_FAQ、FAQ_RECOMMEND |
| `slots`       | Array<SlotDetail> | 槽位数据                                                                            |

- Option

| 字段名          | 类型   | 含义         |
| --------------- | ------ | ------------ |
| `ans_node_name` | string | 推荐的分类   |
| `title`         | string | 推荐标准问题 |
| `answer`        | string | 推荐回答     |
| `confidence`    | float  | 推荐信息指数 |

- SlotDetail

| 字段名  | 类型   | 含义       |
| ------- | ------ | ---------- |
| `name`  | string | 槽位名称   |
| `value` | string | 槽位值     |
| `norm`  | string | 归一化的值 |

## 富文本回答说明

返回数据中 `answer` 为 `string` 类型，除了文本类型的回答外，其他类型的回答都可以通过 `JSON.parse` 解析为 `object` 来查看

### 文本

#### 纯文本类型

```json
{
  "answer": "你好呀，请问你有什么需要帮助"
}
```

#### 文本类型（含推荐问法）

```json
{
  "answer": "暂未找到与之对应的答案，我们会尽快处理。 官方公众号：微信对话开放平台 今天北京多少度"
}
```

#### 文本类型（含超级链接）

```json
{
  "answer": "请前往openai进行配置"
}
```

### 图片

以下展示的 `JSON.parse(answer)` 之后的数据结构

```json
{
  "image": {
    "url": "https://chatbotassets-75050.gzc.vod.tencent-cloud.com/openaiassets_8d8b9f630b619ac507166214590871d0_10652931721011032962.jpg"
  },
  "name": "示例图片"
}
```

`image` 中每个字段描述为：

| 字段 | 类型   | 描述     |
| ---- | ------ | -------- |
| url  | string | 图片 url |
| name | string | 图片标题 |

### 公众号文章

以下展示的 `JSON.parse(answer)` 之后的数据结构

```json
{
  "news": {
    "articles": [
      {
        "title": "新上传视频",
        "description": "",
        "url": "http://mp.weixin.qq.com/s?__biz=MzA4MjA0MjMyMg==&mid=100000020&idx=1&sn=fb056bce6c2ba9975a95286021ae0838&chksm=1f8a8da928fd04bfa590234c94f2dc0c0914aad67283cff1e504f4fd54f8bd05078a752e2c38#rd",
        "picurl": "http://mmbiz.qpic.cn/mmbiz_jpg/qpYIuCdkA73jm0yDo6MwcZ7WP1Loc0c7uVZiaodDPwhibibPMd1asXXt9KRGM0aJEwZSbc9UEKz4qibcOL8kmYqbtQ/0?wx_fmt=jpeg",
        "type": "pm",
        "authorizer_appid": "wx69330177671384f5",
        "public_name": "test1129"
      }
    ]
  }
}
```

`news.articles` 数组中每一项的字段描述为：

| 字段             | 类型   | 描述      |
| ---------------- | ------ | --------- |
| title            | string | 文章标题  |
| description      | string | 文章描述  |
| url              | string | 文章链接  |
| picurl           | string | 图片链接  |
| type             | string | 'pm'      |
| authorizer_appid | string | 公众号 id |
| public_name      | string | 公众号名  |

### 音频

以下展示的 `JSON.parse(answer)` 之后的数据结构

```json
{
  "voice": {
    "id": 28142,
    "url": "https://openai-75050.gzc.vod.tencent-cloud.com/openaiassets_6d2eb1668dba8e73c38e6fc8df78de4f.mp3",
    "name": "Wiz Khalifa _ Chris Brown _ Tyga - See You Again (铃声)"
  }
}
```

`voice` 中每个字段描述为：

| 字段 | 类型   | 描述     |
| ---- | ------ | -------- |
| id   | int    | 音频 id  |
| url  | string | 音频 url |
| name | string | 音频标题 |

若音频文件来源为“公众号素材库”，则会得到如下结果：

```json
{
  "voice": {
    "media_id": "k2fhvmXHM2VFgsLFEcvk93ryEAqourslwoqBOeCXZeorYDKRPDpBptj1bc7i-Pbt",
    "name": "示例音频标题",
    "update_time": 1721011915
  }
}
```

`voice` 中每个字段描述为：

| 字段        | 类型   | 描述                    |
| ----------- | ------ | ----------------------- |
| media_id    | string | 音频 id                 |
| name        | string | 音频标题                |
| update_time | int    | 更新时间（unix 时间戳） |

### 视频

以下展示的 `JSON.parse(answer)` 之后的数据结构

```json
{
  "video": {
    "id": 109754,
    "url": "https://chatbotassets-75050.gzc.vod.tencent-cloud.com/openaiassets_32e63ffc1011bcc82205772cda8b9018_10652931721013199069.mp4",
    "title": "示例视频标题",
    "desc": "视频介绍内容示例，视频介绍内容示例。"
  },
  "name": "示例视频名"
}
```

`video` 中每个字段描述为：

| 字段  | 类型   | 描述     |
| ----- | ------ | -------- |
| id    | int    | 视频 id  |
| url   | string | 视频 url |
| title | string | 视频标题 |
| desc  | string | 视频描述 |
| name  | string | 视频名   |

若视频文件来源为“公众号素材库”，则会得到如下结果：

```json
{
  "video": {
    "media_id": "k2fhvpXHM2VFgsLFEcvk0-6XJJ1md29C_66Geq_yBMYc8yBLkkB6wfI5b6yCHSSQ",
    "title": "示例视频标题",
    "update_time": 1721014129,
    "cover_url": "http://mmbiz.qpic.cn/mmbiz_jpg/IgdWIDQs9UqgBrR12ah1LR9mmq1Ol9TzIHJfVCYiczwZpibt3883f6b1gjGR0lADibwf6PibXm2oSRXS5togvVuLibg/0?wx_fmt=jpeg",
    "description": "视频介绍内容示例，视频介绍内容示例。"
  },
  "name": "示例视频名"
}
```

`video` 中每个字段描述为：

| 字段        | 类型   | 描述                    |
| ----------- | ------ | ----------------------- |
| media_id    | int    | 视频 id                 |
| title       | string | 视频标题                |
| update_time | int    | 更新时间（unix 时间戳） |
| cover_url   | string | 封面图片 url            |
| description | string | 视频描述                |
| name        | string | 视频名                  |

### 小程序

以下展示的 `JSON.parse(answer)` 之后的数据结构

```json
{
  "miniprogrampage": {
    "title": "openai对话插件",
    "appid": "wx8c631f7e9f2465e1",
    "pagepath": "pages/index/index",
    "thumb_media_id": "KegpipQG9t-klMo25My4e8zpBjhjg3JMrMSpgjikB4U",
    "thumb_url": "http://mmbiz.qpic.cn/mmbiz_png/W3gQtpV3j8BYhWgfHT5Hfg6auN94c2ec4BBhDOMtPQrx6vEMc1rR4iaDKxDLOfZ1jBUqIEEY4YpvEj6ktSyXT7g/0?wx_fmt=png"
  }
}
```

`miniprogrampage` 中每个字段描述为：

| 字段           | 类型   | 描述               |
| -------------- | ------ | ------------------ |
| title          | string | 小程序标题         |
| appid          | string | appid              |
| pagepath       | string | 小程序跳转页面路径 |
| thumb_media_id | string | 公众号图片素材 ID  |
| thumb_url      | string | 公众号图片 url     |

### H5

以下展示的 `JSON.parse(answer)` 之后的数据结构

```json
{
  "news": {
    "articles": [
      {
        "title": "实时更新：新型肺炎疫情最新动态",
        "description": "腾讯新闻第一时间同步全国新型肺炎疫情动态，欢迎关注、转发",
        "url": "https://news.qq.com/zt2020/page/feiyan.htm",
        "picurl": "http://mmbiz.qpic.cn/mmbiz_jpg/W3gQtpV3j8D8kZRqfpTJlfVqubwgFQf47H0GWlGV6leaDF80ZpdtuFhQVsCsM3YKmwkujXzdjR2k6aWfA41ic7Q/0?wx_fmt=jpeg",
        "type": "h5"
      }
    ]
  }
}
```

`news.articles` 数组中每一项的字段描述为：

| 字段        | 类型   | 描述     |
| ----------- | ------ | -------- |
| title       | string | H5 标题  |
| description | string | 内容摘要 |
| url         | string | URL 地址 |
| picurl      | string | 封面图片 |
| type        | string | 'h5'     |

### 流式文本

以下展示的 `JSON.parse(answer)` 之后的数据结构

```json
{
  "generate_url": "https://cloudim.weixin.qq.com/cloudim/cloudxw-bin/xwapi/v1/aigc_resolve?id=HwIM1bqCtyefUi5y9AF8--Uf8R-oYoKB5-WbVN5eTx_iABS-_HHuSCAjyUINO3yijOs2ebjHO53xueToj5pJtQAAADY",
  "ref_docs": [
    {
      "doc_name": "基金公司在零钱通中的角色是什么？",
      "ref_contents": [
        {
          "content": "基金公司作为基金产品的提供方，依据法律法规相关要求对基金产品的募集、基金资产的投资、收益分配等基金运作活动进行管理。"
        }
      ]
    }
  ]
}
```

返回数据中每个字段描述为：

| 字段             | 类型                 | 描述     |
| ---------------- | -------------------- | -------- |
| generate_url     | string               | 回答地址 |
| ref_docs         | Array<doc>     | 引用文档 |
| doc.doc_name     | string               | 文档名   |
| doc.ref_contents | Array<content> | 引用内容 |
| content.content  | string               | 引用内容 |

当在问答设置中开启「深度思考」功能后，流式文本回答地址返回的数据中，大模型思考部分会使用 `<think></think>` 标记，并使用换行分隔，具体格式如下：

```

思考内容

回复内容
```

### 合并回答

以下展示的 `JSON.parse(answer)` 之后的数据结构

```js
   //注意：数组的每一项都要转成字符串
  {
    "multimsg": [
      '{"image":{"url":"https://chatbotassets-75050.gzc.v…32947890.jpg"}}',
      '不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤不孤',
      '{"image":{"url":"https://chatbotassets-75050.gzc.v…01698632947890.jpg"}}',
      '送您一首好运来！！！',
      '{"voice":{"id":293,"url":"https://chatbotassets-75050.gzc.v…a83f9d02385a051d2ccbcb67222.mp3","name":"好运来"}}',
      '祝您早日脱单！！！！不孤不孤！！',
      '{"image":{"url":"https://chatbotassets-75050.gzc.v…2947890.jpg"}}'
     ]
  }
```

| 字段     | 类型  | 描述                                                                             |
| -------- | ----- | -------------------------------------------------------------------------------- |
| multimsg | array | 合并回答列表，数组中的每一项为以上单一类型的集合，每一个类型参考其对应的数据结构 |

选择全部回复后，对应 answer 里的数据会有变化，开发者可以根据 `multimsg` 来判断，区分消息适配

![合并回复答案示例](https://res8.wxqcloud.qq.com.cn/wxdoc/f9cafdbf-10ae-4a10-aefd-359fc283d21c.png)

## 加密

介于本接口所传输数据的敏感性，调用本接口时需要额外进行数据加密，加密算法为 AES CBC，具体算法细节可参考 [第三方服务接口](../../thirdapi/thirdapi#%E5%8A%A0%E5%AF%86) 中“加密”一栏的介绍。

## 示例

- 请求示例

```bash
curl 'https://openaiapi.weixin.qq.com/v2/bot/query' \
-H 'X-OPENAI-TOKEN: WVXfTM6cwcIxA0deeCP61XifEeZbMAWXe071YcXciO3ff' \
-H 'X-APPID: Mcf7XpRIQ97ALfW' \
-H 'request_id: 212140c2-b358-4d72-8049-cd4f9053fcc7' \
-H 'timestamp: 1713236762' \
-H 'nonce: bQwdgpvdcs5BV8aZBqK8bbETWM919caJ' \
-H 'sign: e61b9b9bea229dfa97618a3b5750f720' \
-H 'Content-Type: text/plain' \
-d 'QKk1UdeinjDng+sSGRLGeQM5WvtFth0ciD7vpSMPRvFliwPU12BVPTZBVIrma/7hWzCxEBhnE8ScSz6vuYWtD/a67zr1uqw5FYn1IY02ikG+JFJ5eLu8ZX0jTuBDEFGX7iqp88eA/ipPjmE/L2AJhbuvE0kgLFrUaThigYxAU4wUOA0pk/PhRNRSUiZN8KKAcbkaci3XHwvkjhkJgGNEtHlZBzT8/vI17tEMI3opTI9L+BKkMOPdrhRf/cvrN1SSuG4Zm4xB+y/Zxu8Lh8329lY+0Od5UjJngDo3GO2D+LA='
```

加密前的原始数据：

```json
{
  "query": "我叫我妈妈的姐姐叫什么？",
  "env": "online",
  "first_priority_skills": [],
  "second_priority_skills": [],
  "user_name": "测试用户名",
  "avatar": "https://example.com/img/avatar.png",
  "userid": "123"
}
```

- 正确返回示例

接口返回的原始数据：

```text
Vub4qiFmOZnLzDy7x+MhU2HPD5WeyIScQdBso9mYUBMddA2PJcP92tYS3rQ9o2IiJ34pA8dy50snjI0hlaAMZ1I5p/shba26SV/tcvZJDIB/0k0fl154p0wy8bH408tNvlPBBgsLE2rRrUiNFj3X/I8qBHOVTSx691c2zfmlWjUsxvI8Y/YMXTKUx8mXu6ZrxGIEb6ES8BrauNuOOvCWVsOZ8yYIZExal0E5ao+5SjxpPL8j2rx04lIhPbbPjbfwMG0QARonhARQIVJ7dubcGW+3BTd1mlagUnkjttn0kiQ9L1CshZqbJUv7xb+yvGfvqT4q8NB/IXoCNfahBWIKxZWO9knXpbBerPl+f9vkyjHcZ0ggBFlfqzPVFapbVslWBhL56dICrcT4UY2YJqz5b9VSVFknC/iG/bun+IWVO7iZcMr4KsDr1HJ4oLerm2F6Y68GXQqUJP6JavrUW5dakGPJu2QhPu2fxBiP+c0VQ5u4aEfoFozpl6D7UMgRvZLp2LFswVsiUZpLywzyAPj6+2uwf2ExKIMTLSri6iG+HgY=
```

解密后的数据：

```json
{
  "code": 0,
  "data": {
    "answer": "姨妈",
    "answer_type": "text",
    "intent_name": "亲戚关系问询",
    "msg_id": "212140c2-b358-4d72-8049-cd4f9053fcc7",
    "options": null,
    "skill_name": "亲戚关系",
    "slots": [
      {
        "name": "亲戚称呼1",
        "norm": "妈妈",
        "value": "妈妈"
      },
      {
        "name": "亲戚称呼2",
        "norm": "姐姐",
        "value": "姐姐"
      }
    ],
    "status": "GENERAL_FAQ"
  },
  "msg": "success",
  "request_id": "212140c2-b358-4d72-8049-cd4f9053fcc7"
}
```