1. 使用说明

欢迎使用“AICC” API 服务。您可以直接通过标准化的 HTTPS 接口，快速实现平台与自有系统的集成，管理平台的数据配置、呼叫控制、通话记录等各种资源。我们同时还提供了 开发者工具套件（SDK），对 API接口调用进行了封装。推荐您优先使用 SDK ，可以更方便地进行系统集成。

2. 接口规范

2.1. 调用方式

2.1.1. 系统接入

通信协议

出于安全考虑，平台只提供 HTTPS 协议访问，只支持服务端调用，不支持浏览器访问。

字符编码

请求及返回结果都使用 UTF-8 字符集编码。

接入地址

  • 公有云平台:

    • 北京平台：https://api-bj.clink.cn

    • 上海平台：https://api-sh.clink.cn

  • 其它平台: 请咨询技术支持

2.1.2. 公共参数

公共请求参数

每个 API 接口都需要以 URL Parameter 的形式携带公共请求参数，对请求进行鉴权。

名称 类型 是否必须 说明

AccessKeyId

String

是

客服云平台颁发给客户端的访问密钥 ID。

Expires

String

是

签名的有效时间（秒），最小值为 1，最大值为 86400（24 小时）。

Timestamp

String

是

签名的时间戳，格式遵循 ISO 8601 标准，按照格式 “ yyyy-MM-ddTHH:mm:ssZ ” 进行格式化。示例：2018-01-01T12:00:00Z表示北京时间2018年01月01日20点00分00秒

Signature

String

是

根据请求参数和访问密钥计算的签名。

请求示例

https://api-bj.clink.cn/xxxxxx?
&AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af
&Expires=60
&Timestamp=2018-09-11T12:02:34Z
&Signature=A4GDuUoWiFj59wQ0Bfq%2FJnB%2BSRU%3D
...

公共返回参数

名称 类型 说明

requestId

String

请求 ID。无论请求 API 服务是否成功，客服云平台都会返回每个请求的唯一 ID 到客户端。

2.1.3. 签名机制

签名（Signature）的计算需要使用访问密钥对：AccessKeyId/AccessKeySecret。访问密钥对可以通过登录系统管理后台，在【系统管理-系统对接-接口密钥】模块自助生成。每个访问密钥对可以设置不同的接口访问控制权限。

签名算法

签名（Signature）用于对 API 请求进行身份认证和鉴权，每个请求必须具有唯一的签名。 签名的具体实现是以 AccessKeySecret 为密钥，使用 hmac-sha1 算法对用户请求参数（QueryString）、访问密钥ID（AccessKeyId）、签名有效时间（Expires）、签名当前时间戳（Timestamp）做哈希计算。 具体步骤如下：

1. GET示例：

 https://api-bj.clink.cn/cc/list_clients?
 AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af
 &Expires=60
 &Timestamp=2018-10-12T10:18:12Z
 &limit=10
 &offset=0
 &qno=0000
 &cnos[0]=0000
 &cnos[1]=0001

拼接要加密的字符串规则：请求方法（GET）+ 请求域名（api-bj.clink.cn）+ 请求参数。其中，访问密钥ID（AccessKeyId）、签名有效时间（Expires）、签名时间戳（Timestamp）分别与上面的公共请求参数相对应，请求参数具体拼接规则为：

  • 首先对用户请求参数的 name 进行字典排序

AccessKeyId,Expires,Timestamp,cnos[0],cnos[1],limit,offset,qno

  • 通过&符号连接用户请求参数的 name 和 value

AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af&Expires=60&Timestamp=2018-10-12T10:18:12Z&&cnos[0]=0000&cnos[1]=0001&limit=10&offset=0&qno=0000

  • Timestamp为UTC时间格式，所有请求参数都要进行UrlEncode

2018-10-12T10:18:12Z => 2018-10-12T10%3A18%3A12Z
cnos[0] => cnos%5B0%5D
cnos[1] => cnos%5B1%5D

  • 参数urlParam结果

GETapi-bj.clink.cn/cc/list_clients?AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af&Expires=60&Timestamp=2018-10-12T10%3A18%3A12Z&cnos%5B0%5D=0000&cnos%5B1%5D=0001&limit=10&offset=0&qno=0000

  • 计算Signature

Signature = URLEncode(base64(hmac-sha1(AccessKeySecret, urlParam)))

  • 最终请求地址

 https://api-bj.clink.cn/cc/list_clients?
 AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af
 &Expires=60
 &Timestamp=2018-10-12T10%3A18%3A12Z
 &limit=10
 &offset=0
 &qno=0000
 &cnos%5B0%5D
 &cnos%5B1%5D
 &Signature=pDS5pcYkw3SqQV0zk312iCaQJpg%3D

2. POST示例：

 https://api-bj.clink.cn/cc/online?
 AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af
 &Expires=60
 &Timestamp=2018-10-12T10:18:12Z

请求体

{
    "qno":"0000",
    "cnos":["0000","0001"],
    "bindTel":"138xxxx8888",
    "bindType":1,
    "status":1
}

拼接要加密的字符串规则：请求方法（POST）+ 请求域名（api-bj.clink.cn）+ 请求参数（由于POST方法URL中只有公共参数，其他参数通过请求体传递，所以计算签名时只需考虑公共参数）。其中，访问密钥ID（AccessKeyId）、签名有效时间（Expires）、签名时间戳（Timestamp）分别与上面的公共请求参数相对应，请求参数具体拼接规则为：

  • 首先对用户请求参数的 name 进行字典排序

AccessKeyId,Expires,Timestamp

  • 通过&符号连接用户请求参数的 name 和 value

AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af&Expires=60&Timestamp=2018-10-12T10:18:12Z

  • Timestamp为UTC时间格式，所有请求参数都要进行URL转码

2018-10-12T10:18:12Z => 2018-10-12T10%3A18%3A12Z

  • 参数urlParam结果

POSTapi-bj.clink.cn/cc/online?AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af&Expires=60&Timestamp=2018-10-12T10%3A18%3A12Z

  • 计算Signature

Signature = URLEncode(base64(hmac-sha1(AccessKeySecret, urlParam)))

  • 最终请求地址

 https://api-bj.clink.cn/cc/online?
 AccessKeyId=b1fcdc6c62be261cf97b00b25be6a2af
 &Expires=60
 &Timestamp=2018-10-12T10%3A18%3A12Z
 &Signature=pDS5pcYkw3SqQV0zk312iCaQJpg%3D

  • 访问密钥对是访问系统资源的重要凭据，必须严格保密、谨防泄露。

  • 通过使用 SDK，可以简化生成签名和调用 API 的过程。

2.2. 返回结果

API 的返回结果统一为 JSON 格式，使用 UTF-8 字符集编码。为了方便阅读，文中的示例有换行和缩进处理，实际返回结果无换行和缩进处理。

正常返回示例

接口调用成功后，会返回接口调用结果和请求 ID（requestId），HTTP 状态码为 2xx。

示例

{
    "requestId": "c4bc3588-29bd-44be-91d4-d846c8eea64f"
}

分页示例：

{
    "requestId": "77efcfd8-db8c-4f5c-bdb8-d804cfce7423",
    "pageNumber": 1,
    "pageSize": 10,
    "totalCount": 2,
    "objects": [
        {
            "field1":"value1",
            "field2":"value2"
        },
        {
            "field3":"value3",
            "field4":"value4"
        }
    ]
}

异常返回示例

接口调用失败或出错后，会返回错误码、错误信息和请求 ID，HTTP 状态码为 4xx 或 5xx。

您可以根据接口错误码和错误信息排查错误。当您无法排查错误时，可以联系我们的技术支持，并提供 requestId。

示例

{
    "requestId": "778a71c5-7f62-4bbf-b5c2-383a71227b67",
    "error": {
        "code": "ResourceNotFound",
        "message": "指定的资源不存在"
    }
}

2.3. IP白名单

您可以在【系统管理-系统对接-IP白名单】模块中设置对接系统的 IP 白名单，进一步提高数据安全性。如果设置了 IP 白名单，系统只会对指定的 IP 提供 API 服务。系统支持两种 IP 格式：

  • 指定 IP 地址，如：10.10.1.1 。

  • 指定 IP 地址段，如：10.10.1.* - 10.10.2.* 。

2.4. 错误码说明

错误码分为两种类型：

  • 客户端错误：该类型错误由客户端引起，例如无效的请求参数、用户没有权限访问资源等。

  • 服务器错误：该类型错误在服务端产生，由系统异常引起，没有固定的类型。

示例

{
    "requestId": "842ab2a6-3732-4c03-8ab7-c7f83180fb0c",
    "error": {
        "code": "ResourceNotFound",
        "message": "指定的资源不存在"
    }
}

2.4.1. 客户端错误

本节列出了所有操作都可能返回的常见客户端错误。

code HTTP Status message

AuthFailure

401

身份验证失败。

InvalidParameter

400

请求中指定的参数无效，不受支持或无法使用。 返回的消息提供了错误值的说明。

MissingParameter

400

请求缺少必需参数。

ResourceNotFound

404

请求资源不存在。

MissingRequestBody

400

缺少请求body。

MissingAuthenticationToken

400

请求必须包含有效的访问密钥ID。

HttpMediaTypeNotSupported

400

HttpMediaType不支持，只支持application/json

HttpRequestMethodNotSupported

405

HTTP方法不支持。

UnauthorizedOperation

403

您无权执行此操作。请确认您的密钥ID有此权限

UnknownParameter

400

提供了未知或未识别的参数。

SignaturesExpired

403

签名过期

TooManyRequests

429

请求超限

2.4.2. 服务器错误

code HTTP Status message

InternalError

500

发生内部错误。 重试您的请求，但如果问题仍然存在，请联系技术支持。

3. 对话

3.1. 创建会话

创建一个会话。会话是智能体和用户之间的一段问答交互，一个会话包含一条或多条消息。创建会话后可获得唯一的会话ID、开场白等信息。
请求
名称 描述

请求地址

/agent/v1/create-conversation

请求方法

POST

接口频率限制

3次/秒
请求头
名称 值 是否必须

ContentType

application/json

true
请求体参数
名称 类型 是否必需 描述

agent_id

String

true

智能体应用ID。

user

String

true

用户唯一标识。

inputs

Map<String, String>

false

随路参数。包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。默认{}。
请求示例

请求地址

https://api-bj.clink.cn/agent/v1/create-conversation&<公共请求参数>

请求体

{
    "agent_id": "1-2e9bac53-4c44-4d5e-bd4e-717ed69b77a7",
    "user": "anonymous",
    "inputs": {
      "province": "江苏省",
      "city": "南京市"
    }
}
响应参数
名称 类型 描述

conversation_id

String

唯一的会话ID

welcome_statement

WelcomeStatementDTO

开场白

created_at

Long

时间戳（毫秒值）

WelcomeStatementDTO

名称 类型 描述

content

String

开场白话术。

background_pc

String

pc端背景图片url（有效期为3天，请及时转存）。

background_mobile

String

移动端背景图片url（有效期为3天，请及时转存）。

mode

String

热门问模式：simple（简单模式）、category（分类模式）、subject（专题模式）。

display

String

展示模式：column（纵向）、row（横向）。

questions

String[]

问题列表，简单模式下使用。

question_groups

List<QuestionGroupDTO>

问题分组列表，分类模式下使用。

subject_groups

List<SubjectGroupsDTO>

专题分组列表，专题模式下使用。

SubjectGroupsDTO

名称 类型 描述

name

String

主题名称。

icon

String

图标地址（有效期为3天，请及时转存）。

question_groups

List<QuestionGroupDTO>

问题组列表。

QuestionGroupDTO

名称 类型 描述

name

String

问题组名称。

questions

String[]

问题列表。
响应示例

响应体

简单模式

{
  "conversation_id": "0fcac847-ba6a-4d74-b9ac-02d35b9911b5",
  "welcome_statement": {
            "content": "非默认开场白内容",
            "mode": "simple",
            "display": "column",
            "questions":  ["问题1","问题2"],
            "background_pc": "https://xxxx",
            "background_mobile": "https://xxxx",
            "question_groups": null,
            "subject_groups": null
        },
  "created_at": 1728611396109
}

分类模式

{
  "conversation_id": "0fcac847-ba6a-4d74-b9ac-02d35b9911b5",
  "welcome_statement": {
            "content": "非默认开场白内容",
            "mode": "category",
            "display": "column",
            "questions": null,
            "background_pc": "https://xxxx",
            "background_mobile": "https://xxxx",
            "question_groups": [
                        {
                            "name": "问题组1",
                            "questions": [
                                "问题1",
                                "问题2"
                            ]
                        },
                        {
                            "name": "问题组2",
                            "questions": [
                                "问题3",
                                "问题4"
                            ]
                        }
                    ],
            "subject_groups": null
        },
  "created_at": 1728611396109
}

主题模式

{
  "conversation_id": "0fcac847-ba6a-4d74-b9ac-02d35b9911b5",
  "welcome_statement": {
            "content": "非默认开场白内容",
            "mode": "subject",
            "display": "column",
            "questions": null,
            "background_pc": "https://xxxx",
            "background_mobile": "https://xxxx",
            "question_groups": null,
            "subject_groups": [
                {
                    "name": "主题1",
                    "icon": "https://xxxx",
                    "question_groups": [
                        {
                            "name": "问题组1",
                            "questions": [
                                "问题1",
                                "问题2"
                            ]
                        },
                        {
                            "name": "问题组2",
                            "questions": [
                                "问题3",
                                "问题4"
                            ]
                        }
                    ]
                },
                {
                    "name": "主题2",
                    "icon": "https://xxxx",
                    "question_groups": [
                        {
                            "name": "问题组3",
                            "questions": [
                                "问题11",
                                "问题22"
                            ]
                        },
                        {
                            "name": "问题组4",
                            "questions": [
                                "问题33",
                                "问题44"
                            ]
                        }
                    ]
                }
            ]
        },
  "created_at": 1728611396109
}
错误码说明

以下为本接口特有的错误码。更多错误码，请查看错误码说明。

code HTTP Status message

BadRequest

400

（错误的请求，包含具体的错误原因）

3.2. 发送对话消息

发送对话消息。
请求
名称 描述

请求地址

/agent/v1/chat-messages

请求方法

POST

接口频率限制

3次/秒
请求头
名称 值 是否必须

ContentType

application/json

true
请求体参数
名称 类型 是否必需 描述

agent_id

String

true

智能体应用ID。

conversation_id

String

false

会话ID。（不传时会自动生成一个会话ID）

user

String

true

用户唯一标识。

query

List<ChatQueryDTO>

true

用户问题。

inputs

Map<String, String>

false

随路参数。包含了多组键值对（Key/Value pairs），每组的键对应一个特定变量，每组的值则是该变量的具体值。默认{}。

response_mode

String

true

输出模式，可选：streaming（流式模式，类似打字机输出方式的流式返回）、blocking（阻塞模式，等待执行完毕后返回结果）。

ChatQueryDTO

名称 类型 是否必需 描述

content_type

String

true

消息类型，可选：text（文本消息）、file（文件消息）。

content

String

true

消息内容。至少包含一条文本消息，至多包含三条文件消息。当消息类型为file时，content为ChatQueryFileDTO序列化后的JSON字符串。

created_at

Long

false

时间戳（毫秒值）。

ChatQueryFileDTO

名称 类型 是否必需 描述

type

String

true

类型，可选：image（图片）。

transfer_method

String

true

传递方式，可选：remote_url（外部文件）。

file_url

String

当transfer_method=remote_url时必须

外部文件地址。
请求示例

请求地址

https://api-bj.clink.cn/agent/v1/chat-messages&<公共请求参数>

请求体

{
    "agent_id": "1-2e9bac53-4c44-4d5e-bd4e-717ed69b77a7",
    "conversation_id": "0fcac847-ba6a-4d74-b9ac-02d35b9911b5",
    "user": "anonymous",
    "query": [
        {
            "content": "Java类名的规范",
            "content_type": "text",
            "created_at": 1728631299113
        },
        {
            "content": "{\"type\":\"image\",\"transfer_method\":\"remote_url\",\"file_url\":\"https://help.clink.cn/wp-content/uploads/2023/03/1-6.png\"}",
            "content_type": "file",
            "created_at": 1728631299113
        }
    ],
    "inputs": {},
    "response_mode": "blocking"
}
响应体参数

当请求参数 response_mode 为 blocking 时，响应头 Content-Type 为 application/json，响应体为 ChatBlockingResponse。

当请求参数 response_mode 为 streaming 时，响应头 Content-Type 为 text/event-stream，响应体为 ChatStreamingResponse。

ChatBlockingResponse

名称 类型 描述

conversation_id

String

会话ID。

answer

ChatAnswerDTO

回复内容。

ChatStreamingResponse

名称 类型 描述

event

String

事件类型：message（消息）、error（错误信息。流式输出过程中出现的异常会以 stream event 形式输出，收到异常事件后即结束。）、end（结束。收到此事件则代表流式返回结束。）

conversation_id

String

会话ID。

answer

ChatAnswerDTO

回复内容。

ChatAnswerDTO

名称 类型 描述

message_id

String

消息ID。

type

String

回复类型，目前固定为 answer（消息回复）。

content_type

String

消息类型：markdown（Markdown格式的消息）、file（文件消息，只有streaming模式的响应才会包含此类消息类型）

content

String

消息内容。当消息类型为file时，content为ChatAnswerFileDTO序列化后的JSON字符串。

metadata

Map<String,String>

元数据：retriever_resources（引用和归属分段列表）。针对streaming模式的响应，只有event=end结束事件才会包含元数据。

created_at

Long

时间戳（毫秒值）。

ChatAnswerFileDTO

名称 类型 描述

type

String

文件类型：image（图片）。

url

String

文件地址（有效期为3天，请及时转存）。

metadata补充说明

Key Type Description

command

String

指令 transfer_human（转人工）、unknown（未知）、recommend_questions（推荐问）、related_questions（关联问）

vars

Map<String, Objects>

Keys：AGENT_QNO（转人工指令需要转到指定转队列时使用的变量名）、RELATED_QUESTIONS（如果召回的知识中有关联问，会将关联问写入到这个属性）、 RELATED_QUESTIONS_TIPS（如果召回的知识中有关联问，关联问提示语会被写入到这个属性）
响应示例

response_mode 为 blocking 的响应体

{
  "conversation_id": "94154941-4c5e-4f40-a898-bef53a9e84a1",
  "answer": [
    {
      "message_id": "553fa51b-6e5b-46cb-89ae-c2eb3073b2f6",
      "type": "answer",
      "content_type": "markdown",
      "content": "Java 类名规范有以下几点：……",
      "metadata": {
        "command": "related_questions",
        "vars": {
           "RELATED_QUESTIONS_TIPS": "您可能还想要咨询以下问题：",
	       "RELATED_QUESTIONS": ["关联问1", "关联问2"]
        },
        "retriever_resources": [
          {
            "position": 1,
            "dataset_id": "",
            "dataset_name": "",
            "document_id": "file_102013",
            "document_name": "Java开发手册(黄山版).pdf",
            "data_source_type": "",
            "segment_id": 88436,
            "retriever_from": "workflow",
            "score": 0.62765443,
            "hit_count": 0,
            "word_count": 0,
            "segment_position": 0,
            "index_node_hash": "",
            "content": "12.【强制】杜绝完全不规范的英文缩写，避免望文不知义。……",
            "document_link": "https://aikb.clink.cn/open/file/xxxxxx",
            "document_dir": "Java相关"
          },
          {
            //...
          }
        ]
      },
      "created_at": 1728634543000
    }
  ]
}

response_mode 为 streaming 的响应体

// 文本消息事件（markdown格式）
event: message
data: {"event":"message", "answer":[{"content":"Java","content_type":"markdown","created_at":1728634543000,"message_id":"553fa51b-6e5b-46cb-89ae-c2eb3073b2f6"}],"conversation_id":"94154941-4c5e-4f40-a898-bef53a9e84a1"}

// 文件消息事件（image格式）
event: message
data: {"event":"message", "answer":[{"content":"{\"type\":\"image\",\"url\":\"https://help.clink.cn/wp-content/uploads/2023/03/1-6.png\"}","content_type":"file","created_at":1728634543000,"message_id":"553fa51b-6e5b-46cb-89ae-c2eb3073b2f6"}],"conversation_id":"94154941-4c5e-4f40-a898-bef53a9e84a1"}

// 错误事件
event: error
data: {"event": "error", "code": "Bad Request", "message": "智能体应用错误: Run failed: Node 代码执行 run failed"}

// 结束事件
event: end
data: {"event": "end", "conversation_id": "94154941-4c5e-4f40-a898-bef53a9e84a1", "answer": [{"created_at": 1728698606000,"message_id": "553fa51b-6e5b-46cb-89ae-c2eb3073b2f6","metadata": {"command": "related_questions","vars": {"RELATED_QUESTIONS_TIPS":  "您可能还想要咨询以下问题：","RELATED_QUESTIONS": ["关联问1", "关联问2"]},"retriever_resources": [{"position": 1,"dataset_id": "","dataset_name": "","document_id": "file_102013","document_name": "Java开发手册(黄山版).pdf","data_source_type": "","segment_id": 88436,"retriever_from": "workflow","score": 0.62765443,"hit_count": 0,"word_count": 0,"segment_position": 0,"index_node_hash": "","content": "12.【强制】杜绝完全不规范的英文缩写，避免望文不知义……","document_link": "https://aikb-test.clink.cn/open/file/xxxxxx","document_dir": "Java相关"}]}}]}
错误码说明

以下为本接口特有的错误码。更多错误码，请查看错误码说明。

code HTTP Status message

BadRequest

400

（错误的请求，包含具体的错误原因）
特别说明

为确保安全，所有生成的文件链接均为临时有效，且仅在3天内有效，请在有效期内下载或访问。 ---

3.3. 消息反馈

消息反馈。
请求
名称 描述

请求地址

/agent/v1/message-feedback

请求方法

POST

接口频率限制

3次/秒
请求头
名称 值 是否必须

ContentType

application/json

true
请求参数
名称 类型 是否必需 描述

agent_id

String

true

智能体应用ID。

message_id

String

true

消息ID，可从发送对话消息接口的响应内容中获取。

user

String

true

用户唯一标识。

rating

String

true

评价类型：like（点赞）、dislike（点踩）、cancel（撤销）。

tags

List<String>

false

反馈标签。

content

String

false

反馈内容。
请求示例

请求地址

https://api-bj.clink.cn/agent/v1/message-feedback&<公共请求参数>

请求体

{
    "agent_id": "1-3a59b266-sea3-4d2a-8b37-54ea07a23226",
    "message_id": "29831f179-ea7c-49d5-1257-69f15d1e4ed4",
    "user": "xiaom",
    "rating": "like",
    "content": null,
    "tags": null
}
响应参数

该接口无响应体内容（返回空）。

响应示例
{
    "requestId": "118f0d01-2c07-4f0e-a6ba-8c7f90f2e387"
}
错误码说明

以下为本接口特有的错误码。更多错误码，请查看错误码说明。

code HTTP Status message

BadRequest

400

（错误的请求，包含具体的错误原因）