通过 API 获取对话,联系人等数据。
准备工作
点击左下角 「设置」,选择 API,获取 Access Token,同时启用 Access Token

通用
- 调用以下 APIs 时都需要使用 Access Token, Token 重置后将导致上次的 Token 失效。请求头:
Authorization: Bearer YOUR_ACCESS_TOKEN
- 所有请求/响应时间字段均采用毫秒级的 UTCISO 8601 格式,示例:2024-01-01T00:00:00.000Z
接口列表
1. 对话数据查询
注意: 仅支持查询最近 6 个月的数据
1.1 对话数据模型
字段名 | 类型 | 说明 |
ent_id | integer | 企业 ID |
client_info | object | 联系人信息 |
agent_name | string | 客服真实姓名 |
agent_id | integer | 客服 ID |
agent_nick_name | string | 客服昵称 |
agent_work_num | string | 客服工号 |
agent_email | string | 客服邮箱 |
agent_group_name | string | 客服分组名称 |
conv_id | integer | 对话 ID |
track_id | string | 对话访问标识 |
conv_tags | array(string) | 对话标签 |
conv_start_time | string | 对话创建时间 |
conv_end_time | string | 对话结束时间 |
summary | string | 对话小结 |
summary_time | string | 对话小结时间 |
evaluation | integer | 评价类型 0-差评 1-中评 2-好评 |
evaluation_content | string | 评价内容 |
source_type | string | 访问来源 |
source_url | string | 来源 URL |
source | string | 对话渠道 |
sub_source | string | 子渠道名称 |
visit_page_title | string | 着陆页标题 |
visit_page_url | string | 着陆页 URL |
conv_title | string | 对话页标题 |
conv_url | string | 对话页 URL |
search_engine | string | 搜索引擎 |
visitor_os | string | 操作系统 |
visitor_browser | string | 浏览器 |
visitor_location | string | 地区 |
browser_language | string | 浏览器语言 |
utm_source | string | utm_source |
utm_medium | string | utm_medium |
utm_term | string | utm_term |
utm_content | string | utm_content |
utm_campaign | string | utm_campaign |
messages | array(object) | 对话消息列表 |
client_info 对象字段:
字段名 | 类型 | 说明 |
contact_id | string | 联系人 ID |
track_ids | array(string) | 访问标识列表 |
tags | array(string) | 联系人标签 |
system_fields | object | 系统字段,只包含启用显示的字段 |
custom_fields | object | 自定义字段,只包含启用显示的字段 |
messages 对象字段:
字段名 | 类型 | 说明 |
agent_name | string | 消息对应的接待客服真实姓名 |
agent_token | string | 消息对应的接待客服 token |
from | string | 消息来源 |
timestamp | string | 消息时间 |
content | string | 消息内容 |
type | string | 消息类型 |
1.2 根据对话 ID 查询对话详情
接口地址:
GET https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/conversation/{conversation_id}
请求参数:
参数名 | 参数类型 | 类型 | 必填 | 描述 |
conversation_id | Path | integer | 是 | 对话 ID |
响应参数:
字段名 | 类型 | 说明 |
code | integer | 状态码 |
msg | string | 提示信息 |
success | boolean | 是否成功 |
data | 对话数据模型 | 对话数据模型 |
1.3 根据结束时间查询对话列表
接口地址:
GET https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/conversations
请求参数:
参数名 | 参数类型 | 类型 | 必填 | 描述 |
end_time_start | query | string | 是 | 对话结束时间起始值 |
end_time_end | query | string | 是 | 对话结束时间结束值 |
page | query | integer | 否 | 页码,从 1 开始,默认值:1 |
page_size | query | integer | 否 | 每页数量,取值范围:1-50,默认值:20 |
响应参数:
字段名 | 类型 | 说明 |
code | integer | 状态码 |
msg | string | 提示信息 |
success | boolean | 是否成功 |
data | object | 对话列表数据 |
data 对象字段:
字段名 | 类型 | 说明 |
total | integer | 筛选的对话总数 |
data | array(对话数据模型) | 对话数据列表 |
2. 联系人数据查询
注意:联系人字段仅在系统中启用显示时才会返回
2.1 联系人数据模型
字段名 | 类型 | 说明 |
contact_id | string | 联系人 ID |
track_ids | array(string) | 访问标识列表 |
system_fields | object | 系统字段 |
custom_fields | object | 自定义字段 |
2.2 根据创建时间查询联系人列表
接口地址:
GET https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/contacts`
请求参数:
参数名 | 参数类型 | 类型 | 必填 | 描述 |
create_time_start | query | string | 是 | 联系人创建时间起始值 |
create_time_end | query | string | 是 | 联系人创建时间结束值 |
page | query | integer | 否 | 页码,从 1 开始,默认值:1 |
page_size | query | integer | 否 | 每页数量,取值范围:1-50,默认值:20 |
响应参数:
字段名 | 类型 | 说明 |
code | integer | 状态码 |
msg | string | 提示信息 |
success | boolean | 是否成功 |
data | object | 联系人列表数据 |
data 对象字段:
字段名 | 类型 | 说明 |
total | integer | 筛选的联系人总数 |
data | array(联系人数据模型) | 联系人数据列表 |
3. 通过 API 接口发送消息到 Telegram 渠道
Telegram 机器人ID获取方式:添加token时的前面一串数字就是机器人ID

3.1 发送消息数据模型
字段名 | 类型 | 说明 |
tg_bot_id | string | Telegram 机器人ID |
chat_user_id | string | 对话用户id,当前规则群为负,个人为正 |
message_list | array | 发送消息列表;最小1最大10 |
message_list.message_type | string | 消息类型;枚举值:text |
message_list.content | string | 发送消息文本;长度:1-1024 |
3.2 发送文本消息
接口地址:
POST https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/telegram/send
Content-Type: application/json;
请求参数:
发送消息数据模型json格式
响应参数:
字段名 | 类型 | 说明 |
code | integer | 状态码 |
msg | string | 提示信息 |
success | boolean | 是否成功 |
data | object | 发送结果信息 |
data 对象字段:
字段名 | 类型 | 说明 |
message_list | array | 消息 |
message_list 字段:
字段名 | 类型 | 说明 |
conv_id | int64 | 对话id |
msg_id | int64 | 消息id |
示例:
curl --location --request POST 'https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/telegram/send' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 你的 API Token' \
--data-raw '{
"tg_bot_id":"你的 bot id",
"chat_user_id":"你需要发送的 user id",
"message_list":[
{
"message_type":"text",
"content":"你好呀?"
}
]
}'
4.客服服务量
接口地址:
GET https://api.mixdesk.com/mixdesk/hikari/open/api/v1/agent_service
请求参数:
参数名 | 类型 | 必填 | 示例 | 描述 |
create_time_start | string | 是 | 2025-07-10T00:00:00.000Z | 对话结束时间起始值 |
create_time_end | string | 是 | 2025-07-18T00:00:00.000Z | 对话结束时间结束值 |
响应示例:
{
"code": 1,
"msg": "",
"success": true,
"data": [
{
"agent_id": 13,
"agent_name": "超级管理员",
"group_id": 11,
"group_name": "默认分组",
"work_num": "",
"conv_cnt": 0,
"effective_conv_cnt": 0,
"effective_conv_rate": 0,
"missed_conv_cnt": 0,
"missed_conv_rate": 0,
"msg_cnt": 0,
"duration_time": 0,
"conv_first_response_wait_time": 0,
"avg_response_wait_time": 0,
"gold_conv_cnt": 0,
"silver_conv_cnt": 0,
"bronze_conv_cnt": 0,
"nograde_conv_cnt": 0,
"clues_cnt": 0,
"remark_cnt": 0,
"transfer_in_cnt": 0,
"transfer_out_cnt": 0,
"delayed_conv_cnt": 0,
"invited_eval_num": 0,
"good_conv_cnt": 0,
"medium_conv_cnt": 0,
"bad_conv_cnt": 0,
"eval_num": 0,
"eval_rate": 0,
"bad_evaluate_rate": 0,
"medium_evaluate_rate": 0,
"good_evaluate_rate": 0,
"avg_evaluate_score": 0,
"agent_first_response_wait_time": 0,
"clue_conv_cnt": 0,
"avg_human_duration_time": 0
},
{
"agent_id": 486,
"agent_name": "yyy",
"group_id": 11,
"group_name": "默认分组",
"work_num": "002",
"conv_cnt": 0,
"effective_conv_cnt": 0,
"effective_conv_rate": 0,
"missed_conv_cnt": 0,
"missed_conv_rate": 0,
"msg_cnt": 0,
"duration_time": 0,
"conv_first_response_wait_time": 0,
"avg_response_wait_time": 0,
"gold_conv_cnt": 0,
"silver_conv_cnt": 0,
"bronze_conv_cnt": 0,
"nograde_conv_cnt": 0,
"clues_cnt": 0,
"remark_cnt": 0,
"transfer_in_cnt": 0,
"transfer_out_cnt": 0,
"delayed_conv_cnt": 0,
"invited_eval_num": 0,
"good_conv_cnt": 0,
"medium_conv_cnt": 0,
"bad_conv_cnt": 0,
"eval_num": 0,
"eval_rate": 0,
"bad_evaluate_rate": 0,
"medium_evaluate_rate": 0,
"good_evaluate_rate": 0,
"avg_evaluate_score": 0,
"agent_first_response_wait_time": 0,
"clue_conv_cnt": 0,
"avg_human_duration_time": 0
}
]
}
参数解释:
字段 | 参数名 |
客服 ID | agent_id |
客服客服真实姓名 | agent_name |
客服分组 | group_name |
客服分组 ID | group_id |
客服工号 | work_num |
总对话数 | conv_cnt |
总有效对话数 | effective_conv_cnt |
总有效对话率 | effective_conv_rate |
遗漏对话数 | missed_conv_cnt |
遗漏对话率 | missed_conv_rate |
总消息数 | msg_cnt |
转出对话数 | transfer_out_cnt |
转入对话数 | transfer_in_cnt |
平均对话持续时长(秒) | duration_time |
平均人工对话时长 | avg_human_duration_time |
平均对话首次响应时长 | conv_first_response_wait_time |
平均响应时长 | avg_response_wait_time |
客服手动邀评数 | invited_eval_num |
评价数 | eval_num |
评价率 | eval_rate |
好评数 | good_conv_cnt |
好评率 | good_evaluate_rate |
中评数 | medium_conv_cnt |
中评率 | medium_evaluate_rate |
差评数 | bad_conv_cnt |
差评率 | bad_evaluate_rate |
平均评价得分· | avg_evaluate_score |
响应参数:
字段名 | 类型 | 说明 |
code | integer | 状态码 |
msg | string | 提示信息 |
success | boolean | 是否成功 |
data | object | 联系人列表数据 |
状态码
Code | 说明 |
1 | 请求成功 |
10000 | 认证失败,请检查 Access Token |
10010 | 企业版本限制 |
10012 | Access Token 未启用 |
11000 | 请求参数错误 |
20000 | 服务器内部错误 |