Udesk API 通用说明

文档参考 https://www.udesk.cn/website/doc/apiv2/intro/

获取 IM 对话记录列表

该接口用于一次获取多个 IM 对话记录信息 频率限制 1 次/2 秒

请求方法

GET /im/sessions/search

请求参数(Query String)

参数名 必填 说明
start_time 记录开始时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 0 点
end_time 记录结束时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 24 点
status 会话状态(close)
page 页码,从 1 开始,默认为 1
page_size 每页数量,默认 30,最大 1000

注意:

开始时间到结束时间最大时间段为 30 天;

start_time 和 end_time 默认查询的是对话的开始时间, 当 status=close 时按照对话结束时间进行查询;

start_time 和 end_time 的格式为:“YYYY-MM-DD hh:mm:ss”,也可省略时间部分:“YYYY-MM-DD”。

返回数据

属性名 类型 说明
status 整型 执行结果码,0 代表成功
message 字符串 执行结果说明
size 整型 本次返回的数据数量
total 整型 数据总数
total_pages 整型 总页数
item 数组 对话记录列表,每个元素的内容参见IM 数据

示例

curl https://demo.udesk.cn/open_api_v1/im/sessions/search?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回

{
  "status": 0,
  "message": "成功",
  "item": [
    {
      "session_id": 1,
      "sub_session_id": 1,
      "note_id": null,
      "customer_id": 1,
      "customer_name": "测试用户",
      "customer_custom_fields": {},
      "agent_id": 1,
      "agent_nick_name": "测试客服",
      "created_at": "2015-01-01 12:00:00",
      "closed_at": "2015-01-01 12:30:00",
      "resp_seconds": 7,
      "queue_seconds": "未排队",
      "sustain_seconds": 128,
      "survey_vote_id": 1357334,
      "belong_queue": "queue_company_6_group_331",
      "agent_msg_num": 0,
      "customer_msg_num": 0,
      "source": "reocar.udesk.com",
      "source_url": "https://demo.udeskt.cn/im_client/",
      "queue_start_time": "2015-01-01 11:14:49",
      "conversations_num_today": 4,
      "platform": "web",
      "organization_id": null,
      "last_response": "customer",
      "alert_num": 1,
      "alert_desc": "敏感词1次,响应超时,会话超时",
      "ticket_num": 2,
      "ticket_nos": "#140,#141",
      "im_web_plugin_id": 1,
      "sender": "customer",
      "active_guest": "agent",
      "menu_names": "导航菜单",
      "transfer_to_agent": "机器人是否转人工",
      "robot_id": "机器人id",
      "robot_name": "机器人名称",
      "close_method": "sys_close",
      "robot_session_id": 1,
      "resolved_state": "0",
      "web_info": {
        "login_url": null,
        "session_url": "https://demo.udesk.cn/im_client/",
        "keyword": null,
        "src": "demo.udesk.cn",
        "src_url": "https://demo.udesk.cn/im_client/",
        "sys": "Win7",
        "bowser": "Chrome56",
        "generated_channel": null,
        "ip": "123.123.123.123"
      },
      "ticket_ids": []
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

获取 IM 对话记录详情

该接口用于获取某个IM对话的详细信息

请求方法

GET /im/sessions/im_sub_session

请求参数(Query String)

参数名 必填 说明
im_sub_session_id 一次会话的 id

返回数据

属性名 类型 说明
status 整型 执行结果码,0 代表成功
message 字符串 执行结果说明
im_sub_session_log 数组 对话记录详情,每个元素的内容参见IM 数据
im_log_infos 数组 聊天记录,详见im_log_infos参数说明

示例

curl http://demo.udesk.cn/open_api_v1/im/sessions/im_sub_session?im_sub_session_id=1234567&email=admin@udesk.cn&sign_version=v2&nonce=1646221853&timestamp=1646221853&sign=ca821bef91abcd6057ff04024282edbae0856281

返回

{
    "status": 0,
    "message": "成功",
    "im_sub_session_log": [
        {
            "session_id": 1234567,
            "sub_session_id": 123456,
            "note_id": null,
            "customer_id": 123456,
            "customer_name": "xxx",
            "customer_custom_fields": {
                "SelectField_32412442": [
                    "123"
                ]
            },
            "agent_id": 123,
            "agent_nick_name": "xx",
            "created_at": "2022-03-02 15:12:31",
            "closed_at": "2022-03-02 15:13:20",
            "resp_seconds": 28,
            "queue_seconds": "未排队",
            "sustain_seconds": 49,
            "survey_vote_id": 123,
            "resolved_state_title": "问题是否解决?1111111",
            "resolved_state_name": "已解决已解决已解决已",
            "resolved_state_value": "0",
            "platform": "web",
            "belong_queue": "queue_company_28480_agent_148002",
            "agent_msg_num": 3,
            "customer_msg_num": 2,
            "source": "demo.udesk.cn",
            "source_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
            "queue_start_time": "2022-03-02 15:12:31",
            "conversations_num_today": 1,
            "agent_invite_vote_count": null,
            "search_keyword": null,
            "custom_channel": null,
            "organization_id": null,
            "last_response": "agent",
            "alert_num": 1,
            "alert_desc": "敏感词",
            "ticket_num": 0,
            "ticket_nos": null,
            "im_web_plugin_id": 100042,
            "sender": "customer",
            "active_guest": "blank",
            "menu_names": null,
            "transfer_to_agent": false,
            "robot_id": null,
            "robot_name": null,
            "close_method": "agent_close",
            "robot_session_id": null,
            "resolved_state": "0",
            "web_info": {
                "login_url": null,
                "session_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
                "keyword": null,
                "src": "udesk-rd-bj-01.udesk.cn",
                "src_url": "https://demo.udesk.cn/im_client/?web_plugin_id=21&agent_id=12",
                "sys": "Win7",
                "bowser": "Chrome75",
                "generated_channel": null,
                "ip": "123.123.123.123"
            }
        }
    ],
    "im_log_infos": [
        {
            "id": 4359638049,
            "created_at": "2022-03-02 15:12:31",
            "sender": "customer",
            "user_id": 2618228342,
            "content": "{\"type\":\"message\",\"data\":{\"content\":\"有新的咨询进来了。\"},\"im_sub_session_id\":632362082,\"is_welcome\":true}",
            "session_id": 1234567,
            "sub_session_id": 123456,
            "survey_option_id": 1
        },
        {
            "id": 4359638058,
            "created_at": "2022-03-02 15:12:32",
            "sender": "agent",
            "user_id": 148002,
            "content": "{\"type\":\"rich\",\"data\":{\"content\":\"<p><img src=\\\"https://pro-cs-freq.oss-cn-hangzhou.aliyuncs.com/config/imtid28480/1111_1639730293210_js9ng.jpg\\\" /><br />这是全局欢迎语,富文本我去问群</p>\"},\"push_type\":\"sys_welcome_msg\"}",
            "session_id": 1234567,
            "sub_session_id": 123456,
            "survey_option_id": 1
        }
    ]
}

获取某一客户的聊天记录列表

该接口用于一次获取某一用户的聊天记录 频率限制 50 次/60 秒

请求方法

GET /im/sessions/customer_im_logs

请求参数(Query String)

参数名 类型 必填 说明 限制
type 字符串 查询客户的条件类型 不超过 255 个字符
content 字符串 查询客户的条件内容 不超过 255 个字符
start_time 日期时间 记录开始时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 0 点
end_time 日期时间 记录结束时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 24 点
page 整型 页码,从 1 开始,默认为 1

条件类型和内容说明

取值 对应的 content 含义
id 客户 id
email 客户邮箱
cellphone 客户电话
token 客户外部唯一标识,对应值 open_api_token
weixin_open_id 客户微信 openid
weibo_id 客户微博 openid

注意;

记录开始时间到结束时间最大时间段为 90 天;

start_time 和 end_time 查询的是 im_sub_session 的创建时间;

start_time 和 end_time 的格式为:“YYYY-MM-DD hh:mm:ss”,也可省略时间部分:“YYYY-MM-DD”。

返回数据

属性名 类型 说明
status 整型 执行结果码,0 代表成功
message 字符串 执行结果说明
size 整型 本次返回的数据数量
total 整型 数据总数
total_pages 整型 总页数
item 数组 聊天记录列表,每个元素的内容如下

item 的内容

属性名 类型 说明
im_sub_session_id 整型 im_sub_session 的 id
im_log_infos 数组 im_sub_session 下的聊天记录,详情见下

im_log_infos 的内容

属性名 类型 说明
id 整型 im_log 的 id
created_at 日期时间 im_log 的创建时间
sender 字符串 消息发送者
user_id 整型 消息发送者的 id
nick_name 字符串 消息发送者的昵称
content 数组 聊天内容,其中content中的type详见

示例

curl https://demo.udesk.cn/open_api_v1/im/sessions/customer_im_logs?email=admin@udesk.cn&sign_version=v2&nonce=1646278574&sign=b361abcdb6a8a2a42cc137498515cb4054bf32f2&timestamp=1646278574&start_time=2022-03-03 00:00:00&end_time=2022-03-03 23:59:59&page=1&type=id&content=43038556

返回数据

{
    "status": 0,
    "message": "成功",
    "item": [
        {
            "im_sub_session_id": 123,
            "im_log_infos": [
                {
                    "id": 1234,
                    "created_at": "2022-03-03 11:32:59",
                    "sender": "customer",
                    "user_id": 123456,
                    "nick_name": "低调",
                    "content": "{\"type\":\"message\",\"platform\":\"wechat\",\"data\":{\"content\":\"低调低调\",\"duration\":null,\"translation\":null}}"
                }
            ]
        }
    ],
    "size": 1,
    "total": 1,
    "total_pages": 1
}

获取聊天记录列表

该接口用于获取指定 IM 会话的聊天记录信息 频率限制 1 次/2 秒

请求方法

GET /im/sessions/log

请求参数(Query String)

参数名 必填 说明
session_id IM 会话 id
start_time 记录开始时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 0 点
end_time 记录结束时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 24 点
page 页码,从 1 开始,默认为 1
page_size 每页数量,默认 30,最大 1000

start_time 和 end_time 查询的是聊天记录的创建时间; start_time 和 end_time 的格式为:“YYYY-MM-DD hh:mm:ss”,也可省略时间部分:“YYYY-MM-DD”。

返回数据

属性名 类型 说明
status 整型 执行结果码,0 代表成功
message 字符串 执行结果说明
size 整型 本次返回的数据数量
total 整型 数据总数
total_pages 整型 总页数
item 数组 聊天记录列表,每个元素的内容参见下表

item

属性名 类型 说明
id 整型 聊天记录id
created_at 字符串 聊天创建时间
sender 字符串 对话发起方 取值:"customer、agent、sys" 说明:"客户、客服、系统"
user_id 整型 发送人id
content 字符串 消息内容
session_id 整型 所属会话 id
sub_session_id 整型 所属子会话 id
survey_option_id 整型 选择的选项 id

示例

curl https://demo.udesk.cn/open_api_v1/im/sessions/log?email=admin@udesk.cn&sign_version=v2&nonce=1646275242&sign=f72ee9e4f1ef9c925e677538465a76b1be27cd74&timestamp=1646275242&session_id=4324143214&start_time=2022-03-03 00:00:00&end_time=2022-03-03 23:59:59&page=1&page_size=20

返回

{
    "status": 0,
    "message": "成功",
    "item": [
        {
            "id": 1234,
            "created_at": "2022-03-03 10:39:02",
            "sender": "agent",
            "user_id": 17,
            "content": "{\"type\":\"start_session\",\"data\":{\"content\":\"客服手动创建对话\"}}",
            "session_id": 123,
            "sub_session_id": 123456,
            "survey_option_id": null
        },
        {
            "id": 1235,
            "created_at": "2022-03-03 10:39:05",
            "sender": "agent",
            "user_id": 17,
            "content": "{\"type\":\"message\",\"font\":\"font-size:13px;font-weight:normal;font-style:normal;text-decoration:none;color:#1f1f1f;line-height:1.4;\",\"data\":{\"content\":\"阿斯顿撒\",\"richContent\":\"阿斯顿撒\"},\"platform\":\"web\",\"version\":2,\"seq_num\":\"\"}",
            "session_id": 123,
            "sub_session_id": 123456,
            "survey_option_id": null
        }
    ],
    "size": 2,
    "total": 2,
    "total_pages": 1
}

获取满意度调查结果

该接口用于一次获取多个指定时段的满意度调查结果 频率限制 1 次/2 秒

请求方法

GET /im/sessions/vote

请求参数(Query String)

参数名 必填 说明
start_time 记录开始时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 0 点
end_time 记录结束时间:传值时若没有时分秒,则默认时分秒是0时0分0秒。未传值时默认为查询当天 24 点
page 页码,从 1 开始,默认为 1
page_size 每页数量,默认 30,最大 1000

start_time 和 end_time 查询的是满意度调查结果的创建时间; start_time 和 end_time 的格式为:“YYYY-MM-DD hh:mm:ss”,也可省略时间部分:“YYYY-MM-DD”。

返回数据

属性名 类型 说明
status 整型 执行结果码,0 代表成功
message 字符串 执行结果说明
size 整型 本次返回的数据数量
total 整型 数据总数
total_pages 整型 总页数
item 数组 满意度调查结果列表,每个元素的内容参见下文

满意度调查结果

属性名 类型 说明
id 整型 唯一标识
created_at 日期时间 创建时间
session_id 整型 所属会话 id
sub_session_id 整型 所属子会话 id
survey_option_id 整型 选择的选项 id

示例

curl https://demo.udesk.cn/open_api_v1/im/sessions/vote?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回

{
  "status": 0,
  "message": "成功",
  "item": [
    {
      "id": 1,
      "created_at": "2015-01-01 12:00:00",
      "session_id": 1,
      "sub_session_id": 1,
      "survey_option_id": 1,
      "resolved_state": "0",
      "survey_remark": "评价备注",
      "tags": "评价标签"
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

数据结构-IM

IM 对话记录

属性名 类型 说明
sub_session_id 整型 id (同 im_sub_session_id)
session_id 整型 会话 id
robot_session_id 整型 客服系统侧机器人会话 id
note_id 整型 业务记录 id
customer_id 整型 客户 id
customer_name 字符串 客户姓名
customer_custom_fields 对象 客户自定义字段,详见下文
agent_id 整型 客服 id
agent_nick_name 字符串 客服姓名
resp_seconds 整型 响应时间,单位秒
queue_seconds 字符串 排队时间,单位秒
sustain_seconds 整型 持续时间
survey_vote_id 整型 满意度调查结果 id
resolved_state 字符串 满意度-是否已解决, 取值:"0"、"1" 说明:解决、未解决
platform 字符串 渠道,取值:web、微信、微博、android、ios、api
web_info 对象 浏览器访问信息,详见下文
weixin_info 对象 微信访问信息,详见下文
weibo_info 对象 微博访问信息,详见下文
api_info 对象 API 访问信息
ios_info 对象 iOS SDK 访问信息
android_info 对象 Android SDK 访问信息
created_at 日期时间 创建时间
closed_at 日期时间 关闭时间
close_method 字符串 对话结束方式取值:"agent_close"、"redirect_close"、"sys_close"、"customer_close" 说明:客服关闭、转接关闭、系统关闭、客户关闭
belong_queue 字符串 排队队列
agent_msg_num 整型 客服消息数
customer_msg_num 整型 客户消息数
source 字符串 来源
source_url 字符串 来源 url
queue_start_time 日期时间 排队开始时间
conversations_num_today 整型 当日对话次数
search_keyword 字符串 搜索关键词
custom_channel 字符串 自定义渠道信息
agent_invite_vote_count 整型 客服邀评次数
last_response 字符串 最后消息发送方 取值: customer、agent、blank
alert_num 整型 报警次数
alert_desc 字符串 报警项
ticket_num 整型 工单数量
ticket_nos 字符串 工单编号,已逗号","分割
im_web_plugin_id 整型 来源插件 ID
sender 字符串 对话发起方 取值:"customer、agent、sys" 说明:"客户、客服、系统"
active_guest 字符串 访客邀请 取值:"agent、sys、blank" 说明:"客服、自动、无"
ticket_ids 数组 此对话记录对应的工单
organization_id 整型 公司id
menu_names 字符串 导航菜单名称

客户浏览器访问信息

属性名 类型 说明
login_url 字符串
session_url 字符串
keyword 字符串
src 字符串
src_url 字符串 同source_url
sys 字符串
bowser 字符串
generated_channel 字符串
ip 字符串

微信访问信息

属性名 类型 说明
name 字符串 客户微信昵称

微博访问信息

属性名 类型 说明
name 字符串 客户微博昵称

API 访问信息

属性名 类型 说明
from 字符串 固定为"API"

iOS SDK 访问信息

属性名 类型 说明
phone_modal 字符串
phone_version 字符串
app_name 字符串
network_status 字符串
carrier 字符串
scale_screen 字符串

Android SDK 访问信息

属性名 类型 说明
phone_modal 字符串
phone_version 字符串
app_name 字符串
network_status 字符串
carrier 字符串
scale_screen 字符串

IM 聊天记录

属性名 类型 说明
id 整型 唯一标识
created_at 日期时间 创建日期
sender 字符串 发送人身份,agent 或 customer
user_id 整型 发送人 id
content 字符串 消息内容
session_id 整型 所属会话 id
sub_session_id 整型 所属子会话 id
survey_option_id 整型 满意度调查结果 id

错误码说明

错误码 message信息 exception:message信息 描述
2000 当前没有客服在线 无客服处于在线状态,不能创建会话
2065 您的公司无法调用该接口, 请联系udesk技术支持 当前公司未开启"发送消息预览"功能
9200 null 未填写必填参数
机器人参数错误 参数{robot_id}或{scene_id}值错误,未找到数据
缺少参数 XXX,XXX 必填参数{XXX}未填写
对不存在或已删会话评价 XXX 必填参数{im_sub_session_id}未填写或未匹配到值
非法评价 必填参数{option_id}未填写
不可重复评价 参数{im_sub_session_id}对应的会话已经评价过