对话记录接口 - Udesk | 开发者中心

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}对应的会话已经评价过

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Udesk API 通用说明

获取 IM 对话记录列表

请求方法

请求参数（Query String）

返回数据

示例

获取 IM 对话记录详情

请求方法

请求参数（Query String）

返回数据

示例

返回

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

请求方法

请求参数(Query String)

返回数据

示例

返回数据

获取聊天记录列表

请求方法

请求参数（Query String）

返回数据

示例

获取满意度调查结果

请求方法

请求参数（Query String）

返回数据

满意度调查结果

示例

数据结构-IM

IM 对话记录

客户浏览器访问信息

微信访问信息

微博访问信息

API 访问信息

iOS SDK 访问信息

Android SDK 访问信息

IM 聊天记录

错误码说明

文档反馈