客户接口 - Udesk | 开发者中心

获取客户列表

该接口用于一次获取多个客户信息该接口最多只能获取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个字符

注意:

客服id（owner_id）与客服组id（owner_group_id）有关联，当使用参数owner_id时必须添加与之匹配的owner_group_id；

web_token

仅支持字母、数字、@符、小数点、中划线及下划线，禁用其他特殊字符，推荐使用邮箱或电话号码。
如果修改用户的web_token，使用IM用户识别时，web_token也要相应的修改，否则无法识别原有用户。

cellphones

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

weixins

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

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

注意:

appid + openid 是唯一的，如果已经存在则会报错；
appid, openid 为空的条目会被忽略，action 值不正确的条目也会被忽略；
"delete" 操作只能出现在更新客户时，出现在新建客户时会被忽略；
更新客户时，优先执行 "delete" 操作，而后执行 "new" 操作。
微信必须提前绑定到对应客服系统上。操作位置: 客服系统->管理中心->渠道管理->微信

weixin_minis

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

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

注意:

appid + openid 是唯一的，如果已经存在则会报错；
appid, openid 为空的条目会被忽略，action 值不正确的条目也会被忽略；
"delete" 操作只能出现在更新客户时，出现在新建客户时会被忽略；
更新客户时，优先执行 "delete" 操作，而后执行 "new" 操作。
微信小程序必须提前绑定到对应客服系统上。操作位置: 客服系统->管理中心->渠道管理->小程序

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

注意:

corpid + agentid + userid 是唯一的，如果已经存在则会报错；
corpid, agentid, userid 为空的条目会被忽略，action 值不正确的条目也会被忽略；
"delete" 操作只能出现在更新客户时，出现在新建客户时会被忽略；
更新客户时，优先执行 "delete" 操作，而后执行 "new" 操作。

返回数据

与获取客户详情接口相同。

示例

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

该接口的使用方法:

使用 filter_id 或 query 调用该接口, 返回结果中包含第一批数据以及 scroll_id
数据处理完毕后, 使用上一次调用返回的 scroll_id 再次调用该接口(注意此时不需要在传入 filter_id 或 query), 返回结果中包含第二批数据及新的 scroll_id
重复第二步直至返回结果中的 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

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}不在取值范围内

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