即时通讯接口

获取IM对话记录列表

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

请求方法

GET /api/v2/im/session

请求参数(Query String)

参数名 必填 说明
start_time 记录开始时间,默认为查询当天0点
end_time 记录结束时间,默认为查询当天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 http://demo.udesk.cn/api/v2/im/session?page=1&page_size=10&sign=129da7df812jdfsa9912jfdadf81

返回

{
  "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": "http://demo.udeskt.cn/im_client/",
      "queue_start_time": "2015-01-01 11:14:49",
      "conversations_num_today": 4,
      "platform": "web",
      "web_info": {
        "login_url": null,
        "session_url": "http://demo.udesk.cn/im_client/",
        "keyword": null,
        "src": "demo.udesk.cn",
        "src_url": "http://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 /api/v2/im/im_sub_session

请求参数(Query String)

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

返回数据

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

示例

请求

curl http://demo.udesk.com/api/v2/im/im_sub_session?im_sub_session_id=14980761&sign=96689da0e96f12ebf67622413d7d86d5

返回

{
"status": 0,
"message": "成功",
"im_sub_session_log": [
  {
  "session_id": 8761,
  "sub_session_id": 14980761,
  "note_id": null,
  "customer_id": 117092,
  "customer_name": "xx",
  "customer_custom_fields": {},
  "agent_id": 862,
  "agent_nick_name": "xx_客服",
  "created_at": "2017-10-27 21:23:45",
  "closed_at": null,
  "resp_seconds": null,
  "queue_seconds": "未排队",
  "sustain_seconds": 9,
  "survey_vote_id": null,
  "platform": "微信",
  "belong_queue": "queue_company_6_group_271",
  "agent_msg_num": 0,
  "customer_msg_num": 1,
  "source": "微信-xx",
  "source_url": null,
  "queue_start_time": "2017-10-27 21:23:45",
  "conversations_num_today": 3,
  "agent_invite_vote_count": null,
  "search_keyword": null,
  "custom_channel": null,
  "weixin_info": {
    "name": "xx"
  }
  }
],
"im_log_infos": [
  {
  "id": 70161,
  "created_at": "2017-10-27 21:23:54",
  "sender": "customer",
  "user_id": 117092,
  "content": "{"type":"image","platform":"wechat","data":{"content":"https://qn-im.udesk.cn/022c4a12-4f83-492d-8e4d-5f04191e0058.jpg","duration":null,"origin_url":"https://api.weixin.qq.com/cgi-bin/media/get?access_token=Z7kg69qvIqh_5-jZmzmKVgbt3mXP4pvmiNpqt_risTXuF1tOGw2bax9YaSVVQM4PR0HH_q7Fpou3PlYJhujH09xJxQyNmIhGYank_vmMxnEPTJfAHAWAQ&media_id=ObkKKAP5qS8wtFgXi1C2VMHKCZxQxxSvg1YVH2uHuDB_1HfORtcRf_3L2FmCUvO6"}}",
  "session_id": 8761,
  "sub_session_id": 14980761,
  "survey_option_id": null
  },
  {
  "id": 70158,
  "created_at": "2017-10-27 21:23:45",
  "sender": "agent",
  "user_id": 862,
  "content": "{"type":"rich","platform":"wechat","data":{"content":"<p>客服xx_客服_昵称为您服务</p><p>啦啦啦啦啦-英语</p>","duration":null}}",
  "session_id": 8761,
  "sub_session_id": 14980761,
  "survey_option_id": null
  },
  {
  "id": 70157,
  "created_at": "2017-10-27 21:23:45",
  "sender": "customer",
  "user_id": 117092,
  "content": "{"type":"message","platform":"wechat","data":{"content":"有新的咨询进来了。","duration":null}}",
  "session_id": 8761,
  "sub_session_id": 14980761,
  "survey_option_id": null
  },
  {
  "id": 70159,
  "created_at": "2017-10-27 21:23:48",
  "sender": "agent",
  "user_id": 862,
  "content": "{"type":"message","platform":"wechat","data":{"content":"你好微信","duration":null}}",
  "session_id": 8761,
  "sub_session_id": 14980761,
  "survey_option_id": null
  },
  {
  "id": 70160,
  "created_at": "2017-10-27 21:23:52",
  "sender": "agent",
  "user_id": 862,
  "content": "{"type":"message","platform":"wechat","data":{"content":"普通","duration":null}}",
  "session_id": 8761,
  "sub_session_id": 14980761,
  "survey_option_id": null
 }
]
}

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

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

请求方法

GET /api/v2/im/customer_im_logs

请求参数(Query String)

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

条件类型和内容说明

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

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 数组 聊天内容

示例

请求

curl 'http://demo.udeskmonkey.com/api/v2/im/customer_im_logs?type=id&content=4173&start_time=2017-08-10&end_time=2017-11-01&sign=37eec33b035474b62785fd9caefbf0f8'

返回数据

{
    "status": 0,
    "message": "成功",
    "item": [
        {
            "im_sub_session_id": 3852,
            "im_log_infos": [
                {
                    "id": 16834,
                    "created_at": "2017-10-18 16:08:34",
                    "sender": "customer",
                    "user_id": 4173,
                    "nick_name": "udesk测试",
                    "content": "{"type":"message","font":"","data":{"content":"有新的咨询进来了。"},"platform":"android","version":2,"auto":true}"
                },
                {
                    "id": 16836,
                    "created_at": "2017-10-18 16:08:35",
                    "sender": "agent",
                    "user_id": 2,
                    "nick_name": "Tom",
                    "content": "{"type":"close","font":"","data":{"content":"客服Tom关闭对话"},"platform":"android","version":2,"auto":true}"
                },
                {
                    "id": 16837,
                    "created_at": "2017-10-18 16:08:36",
                    "sender": "agent",
                    "user_id": 2,
                    "nick_name": "Tom",
                    "content": "{"type":"survey","font":"","data":{"content":"系统发送满意度调查"},"platform":"android","version":2,"auto":true}"
                }
            ],
        },
        {
            "im_sub_session_id": 3853,
            "im_log_infos": [
                {
                    "id": 16838,
                    "created_at": "2017-10-18 16:08:53",
                    "sender": "customer",
                    "user_id": 4173,
                    "nick_name": "udesk测试",
                    "content": "{"type":"message","font":"","data":{"content":"有新的咨询进来了。"},"platform":"android","version":2,"auto":true}"
                }
            ],
        }
    ],
    "size": 2,
    "total": 2,
    "total_pages": 1
}

获取聊天记录列表

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

请求方法

GET /api/v2/im/log

请求参数(Query String)

参数名 必填 说明
session_id IM会话id
start_time 记录开始时间,默认为查询当天0点
end_time 记录结束时间,默认为查询当天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 数组 聊天记录列表,每个元素的内容参见IM数据

示例

curl http://demo.udesk.cn/api/v2/im/log?session_id=1&page=1&page_size=10&sign=129da7df812jdfsa9912jfdadf81

返回

{
  "status": 0,
  "message": "成功",
  "item": [
    {
      "id": 1,
      "created_at": "2015-01-01 12:00:00",
      "sender": "customer",
      "user_id": 1,
      "content": "{\"type\":\"message\",\"data\":{\"content\":\"有新的咨询进来了。\"},\"im_sub_session_id\":1}",
      "session_id": 1,
      "sub_session_id": 1,
      "survey_option_id": null
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

获取满意度调查结果

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

请求方法

GET /api/v2/im/vote

请求参数(Query String)

参数名 必填 说明
start_time 记录开始时间,默认为查询当天0点
end_time 记录结束时间,默认为查询当天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 http://demo.udesk.cn/api/v2/im/vote?page=1&page_size=10&sign=129da7df812jdfsa9912jfdadf81

返回

{
  "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
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

获取业务记录

该接口用于一次获取多个指定时段的IM业务记录信息 频率限制 1次/2秒

请求方法

GET /api/v2/im/note

请求参数(Query String)

参数名 必填 说明
start_time 记录开始时间,默认为查询当天0点
end_time 记录结束时间,默认为查询当天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 日期时间 创建时间
note_type 字符串 业务记录类型,一般为"im"
session_id 整型 所属会话id
sub_session_id 整型 所属子会话id
content 字符串 内容
custom_fields 数组 自定义字段,详见下文

custom_fields

custom_fields 是一个数组,并且它的每一个元素也是一个包含两个元素的数组,第一个元素为自定义字段的标识名,第二个元素为该字段在此业务记录中的值。

[['标识名', '值']]

业务记录使用的自定义字段的标识名与工单自定义字段是一致的。

详见示例。

示例

curl http://demo.udesk.cn/api/v2/im/note?page=1&page_size=10&sign=129da7df812jdfsa9912jfdadf81

返回

{
  "status": 0,
  "message": "成功",
  "item": [
    {
      "id": 1,
      "created_at": "2015-01-01 12:00:00",
      "note_type": "im",
      "session_id": 1,
      "sub_session_id": 1,
      "content": null,
      "custom_fields": [
        ["TextField_1", "普通文本内容"],                    // 普通文本
        ["TextField_2", "多行文本内容1\r\n多行文本内容2"],  // 多行文本
        ["TextField_3", "2016-08-11"],                      // 日期
        ["TextField_4", "14:44:36"],                        // 时间
        ["TextField_5", "2017-05-03 14:44"],                // 日期时间
        ["TextField_6", "http://www.sample.com"],           // 链接
        ["TextField_7", "13"],                              // 正整数
        ["TextField_8", "13.33"],                           // 数值
        ["SelectField_1", "0"],                             // 下拉列表,下拉选项1
        ["SelectField_2", "0"],                             // 单选框,单选框选项1
        ["SelectField_3", "0,3"]                            // 多选框,多选框选项1、多选框选项4
      ]
    }
  ],
  "size": 1,
  "total": 1,
  "total_pages": 1
}

发送IM结构化消息

该接口用于通过IM向客户发送结构化消息 频率限制 1次/2秒

鉴权

签名方法,参看鉴权方法,但是需要注意以下两点:

请求方法

POST /api/v2/im/struct/messages

请求参数(Query String)

参数名 必填 说明
im_sub_session_id 会话id
customer_id 客户id
agent_id 客服id
timestamp 时间戳

请求参数(Request Body)

参数名 必填 类型 说明
jid_resource 字符串 SDK渠道来源
data 对象 结构话消息

data

参数名 必填 类型 说明
title 字符串 标题
description 字符串 描述
im_url 字符串 显示图片的链接
buttons 数组 按钮列表

buttons元素的结构

参数名 必填 类型 说明
type 字符串 按钮类型
text 字符串 按钮标题
value 字符串 按钮值
callback_name 字符串 回调名称,仅在type为sdk_callback时有效

type的取值范围

取值 含义
link 链接按钮
phone 电话按钮
sdk_callback 回调按钮(仅SDK支持)

返回数据

属性名 类型 说明
status 整型 执行结果码,1000代表成功
message 字符串 执行结果说明

示例

curl http://demo.udesk.cn/api/v2/im/struct/messages?im_sub_session_id=1&customer_id=1&agent_id=1&timestamp=1494814031&sign=129da7df812jdfsa9912jfdadf81 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "data": {
        "title": "测试API发送结构化消息",
        "description": "该消息来自API",
        "img_url": "http://www.udesk.cn/website/images/index/banner01.jpg",
        "buttons": [
            {
                "type": "link",
                "text": "访问",
                "value": "http://www.udesk.cn"
            },
            {
                "type": "phone",
                "text": "拨打电话",
                "value": "010-12345678"
            },
            {
                "type": "sdk_callback",
                "callback_name": "sdk_callback",
                "text": "回调按钮",
                "value": "v1"
            }
        ]
    }
}'

返回

{
  "status": 1000,
  "message": "发送成功"
}

自定义 IM 结构化消息列表页面

自定义 IM 结构化消息列表页面,是一个由️您提供的 HTML 页面,其中包含了常用的结构化消息,以便于客服在 Udesk IM 操作台快速选择并发送给客户。

要使用自定义 IM 结构化消息列表页面,需要以下两步:

  1. 首先需要您编写一个 HTMl 页面,并提供该页面的公网地址;
  2. 在 Udesk 【管理中心】中设置好“嵌入链接”。

编写 HTMl 页面

Udesk 会在客服需要选择结构化消息时,将您提供的 HTML 页面以 iframe 的方式展现给客服,并将以下参数以 Query String 的方式传递给您的 HTML 页面:

参数名 说明
im_sub_session_id 会话id
customer_id 客户id
agent_id 客服id
jid_resource SDK来源
timestamp 时间戳

此外,按照鉴权方法计算出的签名,也会作为 sign 参数一起传递。

计算签名时,与鉴权方法稍有不同,与发送IM结构化消息接口一致。 您在收到请求后,最好先校验 sign 值是否合法,再决定是否返回 HTML 页面。

同时,在 HTML 页面中,您可以用以上参数调用发送IM结构化消息接口,以完成结构化消息的发送。

设置

  1. 使用管理员登录 Udesk 系统;
  2. 打开【管理中心】-【渠道管理】-【即时通讯】-【结构化消息】;
  3. 将“嵌入链接”设置为您提供的 HTML 页面的公网地址。

示例

假设在【管理中心】中的设置如下:

当客服在 IM 工作台聊天界面点击“结构化消息”列表图标时,Udesk 会展示包含类似以下地址的 iframe 页面:

http://www.demo.com/struct_message?im_sub_session_id=1&customer_id=1&agent_id=1&jid_resource=12dsafdaslj129das-12fds912-12dsa&timestamp=1484272693&sign=4666293b3dfe91aa97179dc701be7afc

注意,其中的 sign 的计算方法为:

md5("im_sub_session_id=1&customer_id=1&agent_id=1&timestamp=1484272693&708ff6dc-41d5-4med-9ebc-0388zz9d76f1")
#=> 4666293b3dfe91aa97179dc701be7afc

数据结构-IM

IM对话记录

属性名 类型 说明
sub_session_id 整型 id
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
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 日期时间 关闭时间
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 整型 客服邀评次数

客户浏览器访问信息

属性名 类型 说明
login_url 字符串
session_url 字符串
keyword 字符串
src 字符串
src_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