获取客户列表

该接口用于一次获取多个客户信息 该接口最多只能获取10000条数据, 如果无法需要获取更多的数据, 请使用客户导出接口

请求方法

GET /customers

请求参数(Query String)

参数名 类型 必填 说明 限制
filter_id 整型 客户过滤器id
query 字符串 客户搜索时的关键字
page 整型 页码,从1开始,默认为1
page_size 整型 每页数量,默认20,最大100

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
meta 对象 分页信息,详见通用数据
customers 数组 客户列表,每个客户的说明参见客户数据
wechat 数组 微信渠道信息,详见下文
weibo 数组 微博渠道信息,详见下文
weibo 数组 微博渠道信息,详见下文

wechat

属性名 类型 说明
id 字符串 客户对应公司的第一个微信渠道的app_id
name 字符串 客户对应公司的第一个微信渠道的名称

weibo

属性名 类型 说明
id 字符串 客户对应公司的第一个微博渠道的app_id
name 字符串 客户对应公司的第一个微博渠道的名称

示例

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

返回

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "wechat": [
        {
            "id":   "wxee100100100abc",
            "name": "客户1"
        },
        {
            "id":   "wxee100100100qwe",
            "name": "客户2"
        }
    ],
    "weibo": [
        {
            "id":   "wb1001001001",
            "name": "客户1"
        },
        {
            "id":   "wb1001001002",
            "name": "客户2"
        }
    ],
    "customers": [
        {
            "id": 1,
            "nick_name": "测试用户",
            "level": "normal",
            "description": null,
            "owner_id": 1,
            "owner_group_id": 1,
            "custom_fields": {
                "SelectField_1": ["0"],
                "SelectField_2": ["0"]
            },
            "open_api_token": null,
            "organization_id": null,
            "is_blocked": false,
            "web_token": "dcc79435-e9e2-436a-9cdf-c9f13f728923",
            "sdk_token": "b0bf5c37-ebdd-4539-a961-7941aca02e4c",
            "tags": [],
            "rich_tags": [
                {
                    "id": 1,
                    "name": "富文本标签1",
                    "color": "#70BE72",
                    "company_id": 1
                }
            ],
            "first_contact_at": null,
            "last_contact_at": null,
            "first_contact_at_via_phone": null,
            "last_contact_at_via_phone": null,
            "first_contact_at_via_im": null,
            "last_contact_at_via_im": null,
            "email": "customer@sample.com",
            "other_emails": [],
            "cellphones": [
                {
                  "id": 1,
                  "content": "13000000001"
                }
            ],
            "platform": "手工录入",
            "source_channel": "手动创建",
            "weixins": [
                {
                    "appid": "wxf54489a1azz51885",
                    "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                    "unionid": ""
                }
            ],
            "weixin_minis": [
                {
                    "appid": "wxc7279f8eefd70a4a",
                    "openid": "oa3cT0mano9wVhIpkp3drqy9yDuw",
                    "unionid": ""
                }
            ],
            "weixin_works": [
                {
                    "agentid": "1009117",
                    "corpid": "wxc727955fe6025ed4",
                    "userid": "LS004308",
                    "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DI"
                }
            ]
        }
    ]
}

获取客户详情

该接口用于获取指定条件的客户信息

请求方法

GET /customers/get_customer

请求参数(Query String)

参数名 类型 必填 说明 限制
type 字符串 条件类型,详见下文
content 字符串 条件内容

条件类型

取值 对应content的含义
id 客户id
email 客户邮箱
cellphone 客户电话
token 客户外部唯一标识
weixin_open_id 客户微信openid
weixin_mini_openid 客户微信小程序openid
weixin_work_identifier 客户企业微信的唯一标识,例:cropid:wxc727955fe6025ed4,agentid:1009117,userid:LS004308
weibo_id 客户微博openid
sdk_token 客户sdk标识
web_token 客户web标识

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
customer 对象 客户信息,参见客户数据

示例

curl https://demo.udesk.cn/open_api_v1/customers/get_customer?type=email&content=customer@sample.com&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回

{
    "code": 1000,
    "customer": {
        "id": 1,
        "nick_name": "测试用户",
        "level": "normal",
        "description": null,
        "owner_id": 1,
        "owner_group_id": 1,
        "custom_fields": {
            "SelectField_1": ["0"],
            "SelectField_2": ["0"]
        },
        "open_api_token": null,
        "organization_id": null,
        "is_blocked": false,
        "web_token": "dcc79435-e9e2-436a-9cdf-c9f13f728923",
        "sdk_token": "b0bf5c37-ebdd-4539-a961-7941aca02e4c",
        "tags": [],
        "rich_tags": [
                {
                    "id": 1,
                    "name": "富文本标签1",
                    "color": "#70BE72",
                    "company_id": 1
                }
            ],
        "first_contact_at": null,
        "last_contact_at": null,
        "first_contact_at_via_phone": null,
        "last_contact_at_via_phone": null,
        "first_contact_at_via_im": null,
        "last_contact_at_via_im": null,
        "email": "customer@sample.com",
        "other_emails": [],
        "cellphones": [
            {
              "id": 1,
              "content": "13000000001"
            }
        ],
        "platform": "手工录入",
        "source_channel": "手动创建",
        "weixins": [
            {
                "appid": "wxf54489a1azz51885",
                "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                "unionid": ""
            }
        ],
        "weixin_minis": [
            {
                "appid": "wxc7279f8eefd70a4a",
                "openid": "oa3cT0mano9wVhIpkp3drqy9yDuw",
                "unionid": ""
            }
        ],
        "weixin_works": [
            {
                "agentid": "1009117",
                "corpid": "wxc727955fe6025ed4",
                "userid": "LS004308",
                "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DI"
            }
        ],
        "weixin_kfs": [
            {
                "external_userid": "wmtmN_BgAAj3Sj7j4hv9tD29NoiCZt9A",
                "open_kfid": "wktmN_BgAAuVqNn__Ls5I8dClfOBbAvw",
                "unionid": "o_7Qg6ROh71walfIHr7xtXr-VWDo"
            }
        ]
    }
}

创建客户

该接口用于创建客户

请求方法

POST /customers

请求参数(Request Body)

参数名 类型 必填 说明 限制
customer 对象 客户信息,详见下文
other_emails 数组 其他邮箱列表,具体参见示例
tags 字符串 标签列表,多个标签已逗号分隔

customer

参数名 类型 必填 说明 限制
email 字符串 主邮箱地址 最大长度255个字符
open_api_token 字符串 外部唯一标识 最大长度255个字符
nick_name 字符串 姓名 最大长度255个字符
organization_id 整型 客户公司id
description 字符串 描述 最大长度255个字符
owner_id 整型 负责客服id
owner_group_id 整型 负责客服组id
level 字符串 等级,默认为'normal',取值见客户数据
is_blocked 布尔 是否加入黑名单,默认为false 取值范围为false、true
cellphones 数组 电话列表,详见下文
weixins 数组 微信列表,详见下文
weixin_minis 数组 微信小程序列表,详见下文
weixin_works 数组 企业微信列表,详见下文
custom_fields 对象 自定义字段 "字段类型名称"_"字段唯一ID" 详见
web_token 字符串 客户web标识 最大长度255个字符

注意:

web_token

cellphones

每个元素都是一个数组:[电话id, 电话文本] 新增电话时,电话idnull,详见示例。

weixins

每个元素都是一个对象,包含以下属性:

参数名 类型 必填 说明 限制
action 字符串 执行动作 可选值: "new": 新增, "delete": 删除
appid 字符串 微信应用id
openid 字符串 客户的微信openid
unionid 字符串 客户的微信unionid

注意:

weixin_minis

每个元素都是一个对象,包含以下属性:

参数名 类型 必填 说明 限制
action 字符串 执行动作 可选值: "new": 新增, "delete": 删除
appid 字符串 微信小程序id
openid 字符串 客户的微信小程序openid
unionid 字符串 客户的微信小程序unionid

注意:

weixin_works

每个元素都是一个对象,包含以下属性:

参数名 类型 必填 说明 限制
action 字符串 执行动作 可选值: "new": 新增, "delete": 删除
agentid 字符串 企业微信应用id
userid 字符串 企业微信中的用户id
corpid 字符串 企业微信中的企业id
open_userid 字符串 企业微信供第三方识别的用户id

注意: - 企业微信必须提前绑定到对应客服系统上。操作位置: 客服系统->管理中心->渠道管理->企业微信

weixin_kfs

每个元素都是一个对象,包含以下属性:

参数名 类型 必填 说明 限制
external_userid 字符串 微信客服external_userid
open_kfid 字符串 微信客服open_kfid
unionid 字符串 微信客服unionid

每个元素都是一个对象,包含以下属性:

参数名 类型 必填 说明 限制
action 字符串 执行动作 可选值: "new": 新增, "delete": 删除
agentid 字符串 企业微信应用id
userid 字符串 企业微信中的用户id
corpid 字符串 企业微信中的企业id
open_userid 字符串 企业微信供第三方识别的用户id

注意:

返回数据

获取客户详情接口相同。

示例

curl https://demo.udesk.cn/open_api_v1/customers?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "customer": {
        "email": "customer2@sample.com",
        "nick_name": "测试客户2",
        "owner_id": 1,
        "owner_group_id": 1,
        "level": "vip",
        "is_blocked": false,
        "cellphones": [
            [null, "13100000002"],
            [null, "13200000002"]
        ],
        "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": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "weixins": [
            {
                "action": "new",
                "appid": "wxf54489a1azz51885",
                "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                "unionid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk"
            }
        ],
        "weixin_minis": [
            {
                "action": "new",
                "appid": "wxc7279f8eefd70a4a",
                "openid": "oa3cT0mano9wVhIpkp3drqy9yDuw",
                "unionid": "sadgsathGdfsgBfhkfhgddfxzfAs"
            }
        ],
        "weixin_works": [
            {
                "action": "new",
                "agentid": "1009117",
                "corpid": "wxc727955fe6025ed4",
                "userid": "LS004308",
                "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DI"
            }
        ]
    },
    "other_emails": [
        [null, "customer2@sina.com"],
        [null, "customer2@qq.com"]
    ],
    "tags": "标签1,标签2"
}'

返回

{
    "code": 1000,
    "customer": {
        "id": 1,
        "nick_name": "测试用户",
        "level": "normal",
        "description": null,
        "owner_id": 1,
        "owner_group_id": 1,
        "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": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "open_api_token": null,
        "organization_id": null,
        "is_blocked": false,
        "tags": [
            {
                "id": 1,
                "name": "标签1",
                "company_id": 1
            },
            {
                "id": 1,
                "name": "标签2",
                "company_id": 1
            }
        ],
        "rich_tags": [
                {
                    "id": 1,
                    "name": "富文本标签1",
                    "color": "#70BE72",
                    "company_id": 1
                },
                {
                    "id": 2,
                    "name": "富文本标签2",
                    "color": "#70BE73",
                    "company_id": 1
                }
            ],
        "email": "customer@sample.com",
        "other_emails": [
            [3,"customer2@sina.com"],
            [4,"customer2@qq.com"]
        ],
        "cellphones": [
            {
                "id": 3,
                "content": "13100000002"
            },
            {
                "id": 4,
                "content": "13200000002"
            }
        ],
        "platform": "手工录入",
        "source_channel": "手动创建",
        "weixins": [
            {
                "appid": "wxf54489a1azz51885",
                "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                "unionid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk"
            }
        ],
        "weixin_minis": [
            {
                "appid": "wxc7279f8eefd70a4a",
                "openid": "asdgasda0mano9hIpkp3drqy9yDuw",
                "unionid": "sdagkjalkiairojhjnchfakhajKJa"
            }
        ],
        "weixin_works": [
            {
                "agentid": "1009117",
                "corpid": "wxc727955fe6025ed4",
                "userid": "LS004308",
                "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DI"
            }
        ]
    }
}

更新客户

该接口用于修改客户信息

请求方法

PUT /customers/update_customer

请求参数(Query String)

参数名 必填 说明
type 条件类型
content 条件内容

详见获取客户详情接口

请求参数(Request Body)

创建客户接口相同

返回数据

获取客户详情接口相同。

示例

curl https://demo.udesk.cn/open_api_v1/customers/update_customer?type=email&content=customer@sample.com&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X PUT \
-H 'content-type: application/json' \
-d '
{
    "customer": {
        "level": "normal",
        "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": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "web_token": "dcc79435-e9e2-436a-9cdf-c9f13f728923",
        "sdk_token": "b0bf5c37-ebdd-4539-a961-7941aca02e4c",
        "weixins": [
            {
                "action": "new",
                "appid": "wxf54489a1azz51885",
                "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                "unionid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk"
            },
            {
                "action": "delete",
                "appid": "wxf54489a1azz51885",
                "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk"
            }
        ],
        "weixin_minis": [
            {
                "action": "new",
                "appid": "wxc7279f8eefd70a4a",
                "openid": "oa3cT0mano9wVhIpkp3drqy9yDuw",
                "unionid": "sadgsathGdfsgBfhkfhgddfxzfAs"
            },
            {
                "action": "delete",
                "appid": "wxc7279f8eefd70a4a",
                "openid": "asdgasda0mano9hIpkp3drqy9yDuw"
            }
        ],
        "weixin_works": [
            {
                "action": "new",
                "agentid": "1009117",
                "corpid": "wxc727955fe6025ed4",
                "userid": "LS004308",
                "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DI"
            },
            {
                "action": "delete",
                "agentid": "1009118",
                "corpid": "wxc727955fe6025ed5",
                "userid": "LS004309",
                "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DD"
            }
        ]
    },
    "other_emails": [
        [3, "customer2@sina1.com"]
    ]
}'

返回

{
    "code": 1000,
    "customer": {
        "id": 1,
        "nick_name": "测试用户",
        "level": "normal",
        "description": null,
        "owner_id": 1,
        "owner_group_id": 1,
        "first_contact_at": null,
        "last_contact_at": null,
        "first_contact_at_via_phone": null,
        "last_contact_at_via_phone": null,
        "first_contact_at_via_im": null,
        "last_contact_at_via_im": 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": "https://www.sample.com",
            "TextField_7": "13",
            "TextField_8": "13.33",
            "SelectField_1": ["0"],
            "SelectField_2": ["0"],
            "SelectField_3": ["0","3"]
        },
        "open_api_token": null,
        "organization_id": null,
        "is_blocked": false,
        "web_token": "dcc79435-e9e2-436a-9cdf-c9f13f728923",
        "sdk_token": "b0bf5c37-ebdd-4539-a961-7941aca02e4c",
        "tags": [
            {
                "id": 1,
                "name": "标签1",
                "company_id": 1
            },
            {
                "id": 1,
                "name": "标签2",
                "company_id": 1
            }
        ],
        "rich_tags": [
                {
                    "id": 1,
                    "name": "富文本标签1",
                    "color": "#70BE72",
                    "company_id": 1
                },
                {
                    "id": 2,
                    "name": "富文本标签2",
                    "color": "#70BE73",
                    "company_id": 1
                }
            ],
        "email": "customer@sample.com",
        "other_emails": [
            [3,"customer2@sina1.com"]
        ],
        "cellphones": [
            {
                "id": 3,
                "content": "13100000002"
            },
            {
                "id": 4,
                "content": "13200000002"
            }
        ],
        "platform": "手工录入",
        "source_channel": "手动创建",
        "weixins": [
            {
                "appid": "wxf54489a1azz51885",
                "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                "unionid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk"
            }
        ],
        "weixin_minis": [
            {
                "appid": "wxc7279f8eefd70a4a",
                "openid": "oa3cT0mano9wVhIpkp3drqy9yDuw"
            }
        ],
        "weixin_works": [
            {
                "agentid": "1009117",
                "corpid": "wxc727955fe6025ed4",
                "userid": "LS004308",
                "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DI"
            }
        ]
    }
}

删除客户

该接口用于删除客户信息

请求方法

DELETE /customers/destroy_customer

请求参数(Query String)

参数名 必填 说明
type 条件类型
content 条件内容

详见获取客户详情接口

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
customer_id 整型 删除的客户id

示例

curl https://demo.udesk.cn/open_api_v1/customers/destroy_customer?type=id&content=1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 -X DELETE

返回

{
    "code": 1000,
    "customer_id": 1
}

获取客户历史记录列表

该接口用于获取指定条件客户的历史记录信息

请求方法

GET /customers/feeds

请求参数(Query String)

属性名 必填 说明
type 条件类型
content 条件内容
page 页码,从1开始,默认为1
page_size 每页数量,默认20,最大100

详见获取客户详情接口

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
feeds 数组 客户历史列表,详见下文
meta 对象 分页信息,详见通用数据

feeds元素

feeds的元素分为五类,所有类型的元素,都包含以下属性:

属性名 类型 说明
feed_type 字符串 类型

其取值范围如下:

取值 含义
Ticket 工单
CallLog 通话记录
ImSubSession 对话记录
CustomerFollowUp 跟进记录
Alternation 变更记录

同时,不同类型,还包含各自独有的属性:

Ticket

属性名 类型 说明
id 整型 工单id
subject 字符串 标题
content 字符串 内容
user_id 整型 客户id
user_group_id 整型 负责客服组id
status_zh_name 字符串 工单状态中文名称
created_at 日期时间 工单创建时间

CallLog

属性名 类型 说明
id 整型 通话记录id
call_type 字符串 呼叫类型
result 字符串 通话结果
duration 整型 通话时长
created_at 日期时间 通话创建时间

ImSubSession

属性名 类型 说明
id 整型 对话记录id
platform 字符串 对话平台
customer_msg_num 整型 客户消息数
agent_msg_num 整型 客服消息数
created_at 日期时间 对话创建时间

CustomerFollowUp

属性名 类型 说明
id 整型 跟进记录id
user_id 整型 记录客服id
content 字符串 记录内容
created_at 日期时间 跟进记录创建时间
agent_name 字符串 客服昵称

Alternation

属性名 类型 说明
time 日期时间 变更发生时间
author 对象 操作人
summary 字符串 变更描述

其中,author的格式如下:

属性名 类型 说明
id 整型 客服id
nick_name 字符串 客服昵称

示例

curl https://demo.udesk.cn/open_api_v1/customers/feeds?type=id&content=1&email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回

{
    "code": 1000,
    "feeds": [
        {
            "feed_type": "Ticket",
            "id": 1,
            "content": "<p>测试工单</p>",
            "subject": "测试工单",
            "user_id": 1,
            "user_group_id": 1,
            "status_zh_name": "开启",
            "created_at": "2006-01-02T15:04:05.000+08:00"
        },
        {
            "feed_type": "Alteration",
            "time": "2006-01-02T15:04:05.000+08:00",
            "author": {
                "id": null,
                "nick_name": null
            },
            "summary": "负责人:  <空>---->测试客服1"
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 6
    }
}

获取客户过滤器列表

该接口用于获取全部客户过滤器信息

请求方法

GET /customers/filters

请求参数

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
customer_filters 数组 客户过滤器列表,详见下文

customer_filters元素

属性名 类型 说明
id 整型 唯一标识
name 字符串 名称
active 布尔 是否启用

示例

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

返回

{
    "code": 1000,
    "customer_filters": [
        {
            "id": 1,
            "name": "测试过滤器1",
            "active": true,
        },
        {
            "id": 2,
            "name": "测试过滤器2",
            "active": false,
        }
    ]
}

获取客户自定义字段(废弃)

该接口用于获取全部客户自定义字段信息

请求方法

GET /customers/custom_fields

请求参数

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
custom_fields 数组 客户自定义字段列表,详见下文

custom_fields元素

属性名 类型 说明
id 整型 唯一标识
agent_permission 整型 客服权限
customer_permission 整型 客户权限
custom_field_name 字符串 唯一标识名,通常是"SelectField_"或者"TextField_"前缀加id
title 字符串 字段名
comment 字符串 描述
content_type 字符串 类型
options 数组 选择类型字段的选项,见示例

agent_permission

取值 含义
1 必填
2 选填

customer_permission

取值 含义
0 不可见
1 可见
2 可见且可编辑
3 必填

示例

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

返回

{
    "code": 1000,
    "custom_fields": [
        {
            "id": 1,
            "agent_permission": 1,
            "customer_permission": 2,
            "title": "单行文本字段",
            "comment": "",
            "content_type": "text",
            "custom_field_name": "TextField_1",
            "options": null
        },
        {
            "id": 2,
            "agent_permission": 1,
            "customer_permission": 1,
            "title": "多行文本字段",
            "comment": "",
            "content_type": "area_text",
            "custom_field_name": "TextField_2",
            "options": null
        },
        {
            "id": 3,
            "agent_permission": 1,
            "customer_permission": 3,
            "title": "日期字段",
            "comment": "",
            "content_type": "date",
            "custom_field_name": "TextField_3",
            "options": null
        },
        {
            "id": 4,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_4",
            "title": "时间字段",
            "content_type": "time",
            "comment": "",
            "options": null
        },
        {
            "id": 5,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_5",
            "title": "日期时间字段",
            "content_type": "datetime",
            "comment": "",
            "options": null
        },
        {
            "id": 6,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_6",
            "title": "链接字段",
            "content_type": "link",
            "comment": "",
            "options": null
        },
        {
            "id": 7,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_7",
            "title": "正整数字段",
            "content_type": "number",
            "comment": "",
            "options": null
        },
        {
            "id": 8,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_8",
            "title": "数值字段",
            "content_type": "numeric",
            "comment": "",
            "options": null
        },
        {
            "id": 1,
            "agent_permission": 1,
            "customer_permission": 2,
            "custom_field_name": "SelectField_1",
            "title": "下拉列表字段",
            "content_type": "droplist",
            "comment": null,
            "options": [
                {"0": "下拉选项1"},
                {"1": "下拉选项2"},
                {"2": "下拉选项3"}
            ]
        },
        {
            "id": 2,
            "agent_permission": 1,
            "customer_permission": 2,
            "custom_field_name": "SelectField_2",
            "title": "单选框字段",
            "content_type": "radio",
            "comment": null,
            "options": [
                {"0": "单选框选项1"},
                {"1": "单选框选项2"}
            ]
        },
        {
            "id": 3,
            "agent_permission": 1,
            "customer_permission": 2,
            "custom_field_name": "SelectField_3",
            "title": "多选框字段",
            "content_type": "checkbox",
            "comment": null,
            "options": [
                {"0": "多选框选项1"},
                {"1": "多选框选项2"},
                {"2": "多选框选项3"},
                {"3": "多选框选项4"}
            ]
        }
    ]
}

客户批量导入

该接口用于一次创建多个客户信息 注意:本方法一分钟内只允许调用一次

请求方法

POST /customers/batch_import_async

这个功能是异步的,每次最多导入100个客户。 接口返回code 1000,仅表示导入数据被成功接收,并不表示导入完成。 如果您关心导入结果,则需要配置通知地址,导入完成后,会向通知地址发送通知,具体参看配置通知地址

请求参数(Request Body)

参数名 类型 必填 说明
customers 数组 客户信息数组,详见下文

customers元素

参数名 类型 必填 说明 限制
nick_name 字符串 姓名 最大长度255个字符
description 字符串 描述 最大长度255个字符
emails 数组 邮箱数组
cellphones 数组 电话数组
organization_id 整型 客户公司id
owner_id 整型 负责客服id
owner_group_id 整型 负责客服组id
level 字符串 等级,详见客户数据,默认为"normal"
custom_fields 对象 自定义字段,详见客户数据
tags 字符串 标签,多个是以逗号分隔 最大长度255个字符
open_api_token 字符串 外部唯一标识 最大长度255个字符
weixins 数组 微信信息
weixin_minis 数组 微信小程序信息

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功

示例

curl https://demo.udesk.cn/open_api_v1/customers/batch_import_async?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X POST \
-H 'content-type: application/json' \
-d'
{
    "customers": [
        {
            "nick_name": "测试客户2",
            "emails": ["customer2@sample.com", "customer2@qq.com"],
            "cellphones": ["13100000002", "13200000002"],
            "owner_id": 1,
            "owner_group_id": 1,
            "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": "https://www.sample.com",
                "TextField_7": "13",
                "TextField_8": "13.33",
                "SelectField_1": ["0"],
                "SelectField_2": ["0"],
                "SelectField_3": ["0","3"]
            },
            "weixins": [
                {
                    "appid": "wxf54489a1azz51885",
                    "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                    "unionid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk"
                },
                {
                    "appid": "wxf54489a1azz51885",
                    "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk"
                }
            ],
            "weixin_minis": [
                {
                    "appid": "wxc7279f8eefd70a4a",
                    "openid": "oa3cT0mano9wVhIpkp3drqy9yDuw",
                    "unionid": "sadgsathGdfsgBfhkfhgddfxzfAs"
                },
                {
                    "appid": "wxc7279f8eefd70a4a",
                    "openid": "asdgasda0mano9hIpkp3drqy9yDuw"
                }
            ]
        }
    ]
}'

返回

{
    "code": 1000
}

客户批量导出

该接口用于导出的大量客户信息 支持按照指定过滤器筛选客户 支持按照关键字搜索客户

请求方法

GET /customers/export

该接口的使用方法:

  1. 使用 filter_id 或 query 调用该接口, 返回结果中包含第一批数据以及 scroll_id
  2. 数据处理完毕后, 使用上一次调用返回的 scroll_id 再次调用该接口(注意此时不需要在传入 filter_id 或 query), 返回结果中包含第二批数据及新的 scroll_id
  3. 重复第二步直至返回结果中的 customers 为空

注意: 1. 后续每次调用时,需要使用上一次调用返回的新的 scroll_id,scroll_id 1分钟后过期。 2. filter_id参数错误时会按照无过滤器的方式查询(即返回全部客户)

请求参数(Query String)

参数名 类型 必填 说明 限制
filter_id 整型 客户过滤器id, 导出该过滤器的筛选结果
query 字符串 客户搜索时的关键字, 导出该关键字的搜索结果
scroll_id 字符串 下一批数据的获取id, 从上一次调用本接口的结果中获取

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
scroll_id 字符串 下一批数据的获取id
total 整型 数据总数
customers 数组 客户列表,详见客户数据

注意: 一次获取 customers 的最大数量为1000条; 当返回结果中 customers 数量为0时, 表示导出结束

示例

# 第一次调用
curl https://demo.udesk.cn/open_api_v1/customers/export?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&filter_id=1
# 后续调用
curl https://demo.udesk.cn/open_api_v1/customers/export?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&scroll_id=DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n

返回

{
    "code": 1000,
    "scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAABHFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASBZ1b002REFxcFJGeUtsLUpHWm5lQW1nAAAAAAAAAEkWdW9NNkRBcXBSRnlLbC1KR1puZUFtZwAAAAAAAABKFnVvTTZEQXFwUkZ5S2wtSkdabmVBbWcAAAAAAAAASxZ1b002REFxcFJGeUtsLUpHWm5lQW1n",
    "total": 10000,
    "customers": [...]
}

数据结构-客户

客户

属性名 类型 说明 限制
id 整型 唯一标识
nick_name 字符串 姓名 最大长度255个字符
level 字符串 客户等级
description 字符串 描述 最大长度255个字符
owner_id 整型 负责客服id
owner_group_id 整型 负责客服组id
custom_fields 对象 自定义字段,具体详见下文自定义字段说明
open_api_token 字符串 外部唯一标识 最大长度255个字符
organization_id 整型 客户公司id
organization_ids 数组(整型) 客户公司列表
default_organization_id 整型 默认公司id
is_blocked 布尔 是否被加入黑名单
tags 数组 标签列表,具体详见下文
rich_tags 数组 背景色标签列表,具体详见下文
email 字符串 主邮箱 最大长度255个字符
other_emails 数组 其他邮箱列表
cellphones 数组 联系电话列表
weixins 数组 微信信息
platform 字符串 创建渠道中文名称(该字段将会逐步废弃)
source_channel 字符串 客户来源中文名称
first_contact_at 日期时间 首次联系时间
last_contact_at 日期时间 最后联系时间
first_contact_at_via_phone 日期时间 首次电话联系时间
last_contact_at_via_phone 日期时间 最后电话联系时间
first_contact_at_via_im 日期时间 首次在线客服联系时间
last_contact_at_via_im 日期时间 最后在线客服联系时间
weixin_minis 数组 微信小程序信息
web_token 字符串 客户web标识 最大长度255个字符
sdk_token 字符串 客户sdk标识 最大长度255个字符

level

取值 含义
normal 普通
vip VIP

source_channel

中文名称 英文名称
手动创建 manual
电话呼入 callin
电话呼出 callout
微信 wechat
微博 weibo
在线客服 web_im
API或SDK api
反馈表单 feedback
邮件 mail
批量导入 import
企业微信 qywx
微信客服号 weixin_kf
微信小程序 weixin_mini
百度BCP baidu
推特 twitter
Facebook facebook
Line line
whatsapp whatsapp
抖音企业号 tiktok
视频客服 mpv

platform

中文名称 英文名称
邮件 email
微博 weibo
微信 wechat
即时聊天 im
电话 call
反馈标签 feedback
帮助中心 hc
手工录入 manual_input
API api

tags

属性名 类型 说明
id 整型 标签id
name 字符串 标签名称
company_id 整型 公司id(暂无用途)

rich_tags

属性名 类型 说明
id 整型 标签id
name 字符串 标签名称
color 字符串 标签颜色
company_id 整型 公司id(暂无用途)

custom_fields

custom_fields 示例:

{
    "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": "https://www.sample.com",           // 链接
        "TextField_7": "13",                              // 正整数
        "TextField_8": "13.33",                           // 数值
        "SelectField_1": ["0"],                           // 下拉列表,下拉选项1
        "SelectField_2": ["0"],                           // 单选框,单选框选项1
        "SelectField_3": ["0","3"]                        // 多选框,多选框选项1、多选框选项4
    }
}

合并两个客户的信息

该接口用于合并两个客户的信息

请求方法

POST /customers/merge

请求参数(Query String)

参数名 类型 必填 说明 限制
from_type 字符串 from_type 条件类型,用于查找合并后将被删除的客户,详见下文
from_content 字符串 from_content 条件内容,用于查找合并后将被删除的客户
to_type 字符串 to_type 条件类型,用于查找合并后将被保留的客户,详见下文
to_content 字符串 to_content 条件内容,用于查找合并后将被保留的客户

条件类型

取值 对应content的含义
email 客户邮箱
cellphone 客户电话
customer_token 客户外部唯一标识
weixin_openid 客户微信 openid
weibo_openid 客户微博 openid
sdk_token 客户 sdk 标识
web_token 客户 web 标识
weixin_mini_openid 客户小程序 openid

返回数据

属性名 类型 说明
code 整型 执行结果码,1000代表成功
id 整型 合并后被保留下来的客户的 id

示例

curl https://demo.udesk.cn/open_api_v1/customers/merge?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2 \
-X POST \
-H 'content-type: application/json' \
-d '
{
    "from_type": "email",
    "from_content": "from_customer@sample.com",
    "to_type": "email",
    "to_content": "to_customer@sample.com"
}'

返回

{
    "code": 1000,
    "id": 27
}

code错误码说明

错误码 message信息 exception:message信息 描述
429 api接口超过请求限制 此接口的请求频率超过了限制
2000 未知错误 缺少自定义字段 XXX 当设置自定义字段为必填时,参数{custom_fields}未填写或不符和要求
param is missing or the value is empty: customer {customer}中不含任何参数
邮箱重复:customer id = XXX {email}参数已被id为XXX的客户使用
web_token重复: XXX {web_token}参数已经使用过
web_token格式错误: XXX {web_token}参数格式不符合要求
web_token必须是字符串 {web_token}参数必须
不正确的参数格式 传入参数格式错误
验证失败: 电子邮件是无效的 {email}参数格式错误
微信信息(appid: XXX, openid: XXX)已经存在于客户(id: XXX)中 此微信信息已被id为XXX的客户使用
微信小程序信息(appid: XXX}, openid: XXX)已经存在于客户(id: XXX)中 此微信小程序信息已被id为XXX的客户使用
验证失败: 电话XXX已经使用 {cellphones}中的电话号已被使用
公司id不存在 {organization_id}参数错误
找不到客服 参数{owner_id}错误
客服存在但客服组不存在 只输入客服id{owner_id},还需要输入正确的{owner_group_id}
公司无此客服组 {owner_group_id}参数错误
客服不属于该客服组 参数{owner_group_id}与{owner_id}不匹配
'xxx' is not a valid level 参数{level}输入的值不在取值范围内
undefined method `each' for \"qweasd\":String 输入的{custom_fields}参数格式错误
undefined method `each_with_index' for nil:NilClass {customer}参数为空数组或为null或者此参数未填写
导入数据为空 导入客户数据为空
导入数量(XXX)不能超过100 导入客户数量超过最大限制100了
合并客户失败: 不能合并给自己 合并用户时两个字段指向的是同一个客户
无效的唯一标识符类型 必填参数未填写
Couldn't find Customer 必填参数未填写
2005 没有找到该资源 Couldn't find Customer 提供的参数{content}未找到匹配数据
2060 无效的唯一标识符类型 无效的唯一标识符类型 未传入{type参数}
2062 参数错误 获取客户信息失败 {filter_id}或{scroll_id}参数错误
206211 参数page_size不合法 参数{page_size}不在取值范围内
206201 参数page不合法 参数{page}不在取值范围内