1. Home
  2. Develop Docs
  3. API 开发文档
Searching...

API 开发文档

目录

通过 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_idinteger企业 ID
client_infoobject联系人信息
agent_namestring客服真实姓名
agent_idinteger客服 ID
agent_nick_namestring客服昵称
agent_work_numstring客服工号
agent_emailstring客服邮箱
agent_group_namestring客服分组名称
conv_idinteger对话 ID
track_idstring对话访问标识
conv_tagsarray(string)对话标签
conv_start_timestring对话创建时间
conv_end_timestring对话结束时间
summarystring对话小结
summary_timestring对话小结时间
evaluationinteger评价类型 0-差评 1-中评 2-好评
evaluation_contentstring评价内容
source_typestring访问来源
source_urlstring来源 URL
sourcestring对话渠道
sub_sourcestring子渠道名称
visit_page_titlestring着陆页标题
visit_page_urlstring着陆页 URL
conv_titlestring对话页标题
conv_urlstring对话页 URL
search_enginestring搜索引擎
visitor_osstring操作系统
visitor_browserstring浏览器
visitor_locationstring地区
browser_languagestring浏览器语言
utm_sourcestringutm_source
utm_mediumstringutm_medium
utm_termstringutm_term
utm_contentstringutm_content
utm_campaignstringutm_campaign
messagesarray(object)对话消息列表

client_info 对象字段：

字段名类型说明
contact_idstring联系人 ID
track_idsarray(string)访问标识列表
tagsarray(string)联系人标签
system_fieldsobject系统字段，只包含启用显示的字段
custom_fieldsobject自定义字段，只包含启用显示的字段

messages 对象字段：

字段名类型说明
agent_namestring消息对应的接待客服真实姓名
agent_tokenstring消息对应的接待客服 token
fromstring消息来源
timestampstring消息时间
contentstring消息内容
typestring消息类型

1.2 根据对话 ID 查询对话详情

接口地址：

GET https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/conversation/{conversation_id}

请求参数：

参数名参数类型类型必填描述
conversation_idPathinteger是对话 ID

响应参数：

字段名类型说明
codeinteger状态码
msgstring提示信息
successboolean是否成功
data对话数据模型对话数据模型

1.3 根据结束时间查询对话列表

接口地址：

GET https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/conversations

请求参数：

参数名参数类型类型必填描述
end_time_startquerystring是对话结束时间起始值
end_time_endquerystring是对话结束时间结束值
pagequeryinteger否页码，从 1 开始，默认值：1
page_sizequeryinteger否每页数量，取值范围：1-50，默认值：20

响应参数：

字段名类型说明
codeinteger状态码
msgstring提示信息
successboolean是否成功
dataobject对话列表数据

data 对象字段：

字段名类型说明
totalinteger筛选的对话总数
dataarray(对话数据模型)对话数据列表

2. 联系人数据查询

注意：联系人字段仅在系统中启用显示时才会返回

2.1 联系人数据模型

字段名类型说明
contact_idstring联系人 ID
track_idsarray(string)访问标识列表
system_fieldsobject系统字段
custom_fieldsobject自定义字段

2.2 根据创建时间查询联系人列表

接口地址：

GET https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/contacts`

请求参数：

参数名参数类型类型必填描述
create_time_startquerystring是联系人创建时间起始值
create_time_endquerystring是联系人创建时间结束值
pagequeryinteger否页码，从 1 开始，默认值：1
page_sizequeryinteger否每页数量，取值范围：1-50，默认值：20

响应参数:

字段名类型说明
codeinteger状态码
msgstring提示信息
successboolean是否成功
dataobject联系人列表数据

data 对象字段：

字段名类型说明
totalinteger筛选的联系人总数
dataarray(联系人数据模型)联系人数据列表

3. 通过 API 接口发送消息到 Telegram 渠道

Telegram 机器人ID获取方式：添加token时的前面一串数字就是机器人ID

3.1 发送消息数据模型

字段名类型说明
tg_bot_idstringTelegram 机器人ID
chat_user_idstring对话用户id，当前规则群为负，个人为正
message_listarray发送消息列表；最小1最大10
message_list.message_typestring消息类型；枚举值：text
message_list.contentstring发送消息文本；长度：1-1024

3.2 发送文本消息

接口地址： 

POST https://api-gateway.mixdesk.com/mixdesk/hikari/open/api/v1/telegram/send

Content-Type: application/json;

请求参数：

发送消息数据模型json格式

响应参数:

字段名类型说明
codeinteger状态码
msgstring提示信息
successboolean是否成功
dataobject发送结果信息

data 对象字段：

字段名类型说明
message_listarray消息

message_list 字段：

字段名类型说明
conv_idint64对话id
msg_idint64消息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_startstring是2025-07-10T00:00:00.000Z对话结束时间起始值
create_time_endstring是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
        }
    ]
}

参数解释：

字段参数名
客服 IDagent_id
客服客服真实姓名agent_name
客服分组group_name
客服分组 IDgroup_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

响应参数:

字段名类型说明
codeinteger状态码
msgstring提示信息
successboolean是否成功
dataobject联系人列表数据

状态码

Code说明
1请求成功
10000认证失败，请检查 Access Token
10010企业版本限制
10012Access Token 未启用
11000请求参数错误
20000服务器内部错误
Updated on 2025年7月23日
Was this article helpful?
Yes No

Related Articles