Udesk-Customer service solution leader

Retrieve Customer List

This interface is used to retrieve information for multiple customers at once. This interface can retrieve up to 10,000 pieces of data. If you need to retrieve more data, please use the Customer Export Interface.

Request Method

GET /customers

Request Parameters (Query String)

Parameter Name	Type	Required	Description
filter_id	Integer	No	Customer filter ID
query	String	No	Keyword for customer search
page	Integer	No	Page number, starting from 1, default is 1
page_size	Integer	No	Number of items per page, default is 20, maximum is 100

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
meta	Object	Pagination information, see Common Data
customers	Array	Customer list, see Customer Data for each customer's description
wechat	Array	WeChat channel information, see below
weibo	Array	Weibo channel information, see below

wechat

Attribute Name	Type	Description
id	String	The app_id of the first WeChat channel corresponding to the customer's company
name	String	The name of the first WeChat channel corresponding to the customer's company

weibo

Attribute Name	Type	Description
id	String	The app_id of the first Weibo channel corresponding to the customer's company
name	String	The name of the first Weibo channel corresponding to the customer's company

Example

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

Response

{
    "code": 1000,
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 1
    },
    "wechat": [
        {
            "id":   "wxee100100100abc",
            "name": "customer 1"
        },
        {
            "id":   "wxee100100100qwe",
            "name": "customer 2"
        }
    ],
    "weibo": [
        {
            "id":   "wb1001001001",
            "name": "customer 1"
        },
        {
            "id":   "wb1001001002",
            "name": "customer 2"
        }
    ],
    "customers": [
        {
            "id": 1,
            "nick_name": "Test User",
            "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": "Rich text label 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": "Manual entry",
            "source_channel": "Manual creation",
            "weixins": [
                {
                    "appid": "wxf54489a1azz51885",
                    "openid": "og8dL0nfmm7wVjIVzk1deqt9Vkdk",
                    "unionid": ""
                }
            ],
            "weixin_minis": [
                {
                    "appid": "wxc7279f8eefd70a4a",
                    "openid": "oa3cT0mano9wVhIpkp3drqy9yDuw",
                    "unionid": ""
                }
            ],
            "weixin_works": [
                {
                    "agentid": "1009117",
                    "corpid": "wxc727955fe6025ed4",
                    "userid": "LS004308",
                    "open_userid": "o0Nng1Sdt5EFl8ZQ8qKAIpOuV9DI"
                }
            ]
        }
    ]
}

Retrieve Customer Details

This interface is used to retrieve information for specified customers.

Request Method

GET /customers/get_customer

Request Parameters (Query String)

Parameter Name	Type	Required	Description	Restrictions
type	String	Yes	Condition type, see below
content	String	Yes	Condition content

Condition Type

Value	Meaning of `content`
id	Customer ID
email	Customer email
cellphone	Customer phone number
token	Customer external unique identifier
weixin_open_id	Customer WeChat openid
weixin_mini_openid	Customer WeChat Mini Program openid
weixin_work_identifier	Customer Enterprise WeChat unique identifier, e.g., cropid:wxc727955fe6025ed4,agentid:1009117,userid:LS004308
weibo_id	Customer Weibo openid
sdk_token	Customer SDK identifier
web_token	Customer web identifier

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
customer	Object	Customer information, see Customer Data

Example

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

Response

{
    "code": 1000,
    "customer": {
        "id": 1,
        "nick_name": "Test User",
        "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": "Rich text label 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": "Manual entry",
        "source_channel": "Manual creation",
        "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"
            }
        ]
    }
}

Create Customer

This interface is used to create a customer.

Request Method

POST /customers

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
customer	Object	Yes	Customer information, see below
other_emails	Array	No	List of other email addresses, see example
tags	String	No	List of tags, separated by commas

customer

Parameter Name	Type	Required	Description	Constraints
email	String	No	Primary email address	Maximum length 255 characters
open_api_token	String	No	External unique identifier	Maximum length 255 characters
nick_name	String	Yes	Name	Maximum length 255 characters
organization_id	Integer	No	Customer company ID
description	String	No	Description	Maximum length 255 characters
owner_id	Integer	No	Responsible customer service ID
owner_group_id	Integer	No	Responsible customer service group ID
level	String	No	Level, default is 'normal', see Customer Data
is_blocked	Boolean	No	Whether to add to the blacklist, default is false	Options are false, true
cellphones	Array	No	List of phones, see below
weixins	Array	No	List of WeChat accounts, see below
weixin_minis	Array	No	List of WeChat Mini Programs, see below
weixin_works	Array	No	List of Enterprise WeChat accounts, see below
custom_fields	Object	No	Custom fields	"Field Type Name"_"Field Unique ID" See
web_token	String	No	Customer web token	Maximum length 255 characters

Note:

The customer service ID (owner_id) is associated with the customer service group ID (owner_group_id). When using the parameter owner_id, the matching owner_group_id must be added.

web_token

Only letters, numbers, @ symbol, period, hyphen, and underscore are supported. Special characters other than these are not allowed. It is recommended to use email or phone numbers.
If you modify a user's web_token, you must also modify the web_token when using IM User Identification, otherwise the original user cannot be recognized.

cellphones

Each element is an array: [phone_id, phone_text] When adding a new phone, phone_id is null, see example.

weixins

Each element is an object with the following attributes:

Parameter Name	Type	Required	Description	Constraints
action	String	Yes	Action to perform	Options: "new": Add, "delete": Delete
appid	String	Yes	WeChat application ID
openid	String	Yes	Customer's WeChat openid
unionid	String	No	Customer's WeChat unionid

Note:

appid + openid is unique, an error will occur if it already exists;
Entries with empty appid and openid will be ignored, as will entries with incorrect action values;
The "delete" operation can only appear when updating customers, it will be ignored if it appears when creating new customers;
When updating customers, the "delete" operation is performed first, followed by the "new" operation.
WeChat must be bound to the corresponding customer service system in advance. Operation location: Customer Service System->Management Center->Channel Management->WeChat

weixin_minis

Each element is an object containing the following attributes:

Parameter Name	Type	Required	Description	Restrictions
action	String	Yes	Action to be performed	Optional values: "new": Add, "delete": Delete
appid	String	Yes	WeChat Mini Program ID
openid	String	Yes	Customer's WeChat Mini Program OpenID
unionid	String	No	Customer's WeChat Mini Program UnionID

Notes:

appid + openid is unique, and an error will be reported if it already exists;
Entries with empty appid, openid will be ignored, as well as those with incorrect action values;
The "delete" operation can only appear when updating a customer and will be ignored when creating a new customer;
When updating a customer, the "delete" operation is performed first, followed by the "new" operation.
WeChat Mini Programs must be bound to the corresponding customer service system in advance. Location: Customer Service System -> Management Center -> Channel Management -> Mini Program

weixin_works

Each element is an object containing the following attributes:

Parameter Name	Type	Required	Description	Restrictions
action	String	Yes	Action to be performed	Optional values: "new": Add, "delete": Delete
agentid	String	Yes	Enterprise WeChat Application ID
userid	String	Yes	User ID in Enterprise WeChat
corpid	String	Yes	Enterprise ID in Enterprise WeChat
open_userid	String	No	User ID for third-party identification in Enterprise WeChat

Notes:

Enterprise WeChat must be bound to the corresponding customer service system in advance. Location: Customer Service System -> Management Center -> Channel Management -> Enterprise WeChat

weixin_kfs

Each element is an object containing the following attributes:

Parameter Name	Type	Required	Description
external_userid	String	No	WeChat Customer Service external_userid
open_kfid	String	No	WeChat Customer Service open_kfid
unionid	String	No	WeChat Customer Service unionid

Each element is an object containing the following attributes:

Parameter Name	Type	Required	Description	Restrictions
action	String	Yes	Action to be performed	Optional values: "new": Add, "delete": Delete
agentid	String	Yes	Enterprise WeChat Application ID
userid	String	Yes	User ID in Enterprise WeChat
corpid	String	Yes	Enterprise ID in Enterprise WeChat
open_userid	String	No	User ID for third-party identification in Enterprise WeChat

Notes:

corpid + agentid + userid is unique, and an error will be reported if it already exists;
Entries with empty corpid, agentid, userid will be ignored, as well as those with incorrect action values;
The "delete" operation can only appear when updating a customer and will be ignored when creating a new customer;
When updating a customer, the "delete" operation is performed first, followed by the "new" operation.

Response Data

The response data is the same as the Get Customer Details API.

Example

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": "demo customer 2",
        "owner_id": 1,
        "owner_group_id": 1,
        "level": "vip",
        "is_blocked": false,
        "cellphones": [
            [null, "13100000002"],
            [null, "13200000002"]
        ],
        "custom_fields": {
            "TextField_1": "Plain text content",
            "TextField_2": "Multiline text content 1\r\nMultiline text content 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": "tag1,tag2"
}'

Response

{
    "code": 1000,
    "customer": {
        "id": 1,
        "nick_name": "Test User",
        "level": "normal",
        "description": null,
        "owner_id": 1,
        "owner_group_id": 1,
        "custom_fields": {
            "TextField_1": "Plain text content",
            "TextField_2": "Multiline text content 1\r\nMultiline text content 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": "tag1",
                "company_id": 1
            },
            {
                "id": 1,
                "name": "tag2",
                "company_id": 1
            }
        ],
        "rich_tags": [
                {
                    "id": 1,
                    "name": "Rich text label 1",
                    "color": "#70BE72",
                    "company_id": 1
                },
                {
                    "id": 2,
                    "name": "Rich text label 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": "Manual entry",
        "source_channel": "Manual creation",
        "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"
            }
        ]
    }
}

Update Customer

This interface is used to modify customer information.

Request Method

PUT /customers/update_customer

Request Parameters (Query String)

Parameter Name	Required	Description
type	Yes	Condition Type
content	Yes	Condition Content
For more details, see the Get Customer Details API.

Request Parameters (Request Body)

The same as the Create Customer Interface.

Response Data

The same as the Get Customer Details API.

Example

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": "Plain text content",
            "TextField_2": "Multiline text content 1\r\nMultiline text content 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"]
    ]
}'

Response

{
    "code": 1000,
    "customer": {
        "id": 1,
        "nick_name": "Test User",
        "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": "Plain text content",
            "TextField_2": "Multiline text content 1\r\nMultiline text content 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": "tag1",
                "company_id": 1
            },
            {
                "id": 1,
                "name": "tag2",
                "company_id": 1
            }
        ],
        "rich_tags": [
                {
                    "id": 1,
                    "name": "Rich text label 1",
                    "color": "#70BE72",
                    "company_id": 1
                },
                {
                    "id": 2,
                    "name": "Rich text label 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": "Manual entry",
        "source_channel": "Manual creation",
        "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 Customer

This interface is used to delete customer information.

Request Method

DELETE /customers/destroy_customer

Request Parameters (Query String)

Parameter Name	Required	Description
type	Yes	Condition Type
content	Yes	Condition Content
For more details, see the Get Customer Details API.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
customer_id	Integer	Deleted customer ID

Example

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

Response

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

Get Customer History List

This interface is used to obtain the historical record information of specified condition customers.

Request Method

GET /customers/feeds

Request Parameters (Query String)

Attribute Name	Required	Description
type	Yes	Condition Type
content	Yes	Condition Content
page	No	Page number, starting from 1, default is 1
page_size	No	Number of items per page, default is 20, maximum is 100
For more details, see the Get Customer Details API.

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
feeds	Array	Customer history list, see below
meta	Object	Pagination information, see Common Data

feeds Elements

The elements of feeds are divided into five categories, and all types of elements contain the following attributes:

Attribute Name	Type	Description
feed_type	String	Type

The range of values is as follows:

Value	Meaning
Ticket	Ticket
CallLog	Call Log
ImSubSession	Chat Record
CustomerFollowUp	Follow-up Record
Alternation	Change Record

At the same time, different types also contain their own unique attributes: Ticket

Attribute Name	Type	Description
id	Integer	Ticket ID
subject	String	Title
content	String	Content
user_id	Integer	Customer ID
user_group_id	Integer	Responsible Customer Service Group ID
status_zh_name	String	Ticket Status in Chinese
created_at	Date-Time	Ticket Creation Time

CallLog

Attribute Name	Type	Description
id	Integer	Call Log ID
call_type	String	Call Type
result	String	Call Result
duration	Integer	Call Duration
created_at	Date-Time	Call Creation Time

ImSubSession

Attribute Name	Type	Description
id	Integer	Chat Record ID
platform	String	Chat Platform
customer_msg_num	Integer	Number of Customer Messages
agent_msg_num	Integer	Number of Customer Service Messages
created_at	Date-Time	Chat Creation Time

CustomerFollowUp

Attribute Name	Type	Description
id	Integer	Follow-up Record ID
user_id	Integer	Customer Service ID
content	String	Record Content
created_at	Date-Time	Follow-up Record Creation Time
agent_name	String	Customer Service Nickname

Alternation

Attribute Name	Type	Description
time	Date-Time	Time of Change
author	Object	Operator
summary	String	Change Description

The format of the author is as follows:

Attribute Name	Type	Description
id	Integer	Customer Service ID
nick_name	String	Customer Service Nickname

Example

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

Response

{
    "code": 1000,
    "feeds": [
        {
            "feed_type": "Ticket",
            "id": 1,
            "content": "<p>Demo Ticket</p>",
            "subject": "Demo Ticket",
            "user_id": 1,
            "user_group_id": 1,
            "status_zh_name": "open",
            "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": "Responsible person: [None] --> Test Customer Service 1 "
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "total_count": 6
    }
}

Get Customer Filter List

This interface is used to obtain information about all customer filters.

Request Method

GET /customers/filters

Request Parameters

None

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
customer_filters	Array	List of customer filters, see below

customer_filters Elements

Attribute Name	Type	Description
id	Integer	Unique Identifier
name	String	Name
active	Boolean	Is Active

Example

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

Response

{
    "code": 1000,
    "customer_filters": [
        {
            "id": 1,
            "name": "Test Filter 1",
            "active": true,
        },
        {
            "id": 2,
            "name": "Test Filter 2",
            "active": false,
        }
    ]
}

Get Customer Custom Fields (Deprecated)

This interface is used to obtain information about all customer custom fields.

Request Method

GET /customers/custom_fields

Request Parameters

None

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
custom_fields	Array	List of customer custom fields, see below

custom_fields Elements

Attribute Name	Type	Description
id	Integer	Unique Identifier
agent_permission	Integer	Agent Permission
customer_permission	Integer	Customer Permission
custom_field_name	String	Unique Identifier Name, usually "SelectField_" or "TextField_" prefix with id
title	String	Field Name
comment	String	Description
content_type	String	Type
options	Array	Options for selection type fields, see example

agent_permission

Value	Meaning
1	Required
2	Optional

customer_permission

Value	Meaning
0	Invisible
1	Visible
2	Visible and Editable
3	Required

Example

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

Response

{
    "code": 1000,
    "custom_fields": [
        {
            "id": 1,
            "agent_permission": 1,
            "customer_permission": 2,
            "title": "Single-line text field",
            "comment": "",
            "content_type": "text",
            "custom_field_name": "TextField_1",
            "options": null
        },
        {
            "id": 2,
            "agent_permission": 1,
            "customer_permission": 1,
            "title": "Multiline text field",
            "comment": "",
            "content_type": "area_text",
            "custom_field_name": "TextField_2",
            "options": null
        },
        {
            "id": 3,
            "agent_permission": 1,
            "customer_permission": 3,
            "title": "Date Field",
            "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": "Time Field",
            "content_type": "time",
            "comment": "",
            "options": null
        },
        {
            "id": 5,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_5",
            "title": "Date Time Field",
            "content_type": "datetime",
            "comment": "",
            "options": null
        },
        {
            "id": 6,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_6",
            "title": "Link Field",
            "content_type": "link",
            "comment": "",
            "options": null
        },
        {
            "id": 7,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_7",
            "title": "Positive integer field",
            "content_type": "number",
            "comment": "",
            "options": null
        },
        {
            "id": 8,
            "agent_permission": 1,
            "customer_permission": 3,
            "custom_field_name": "TextField_8",
            "title": "Numeric field",
            "content_type": "numeric",
            "comment": "",
            "options": null
        },
        {
            "id": 1,
            "agent_permission": 1,
            "customer_permission": 2,
            "custom_field_name": "SelectField_1",
            "title": "Drop List Field",
            "content_type": "droplist",
            "comment": null,
            "options": [
                {"0": "option 1"},
                {"1": "option 2"},
                {"2": "option 3"}
            ]
        },
        {
            "id": 2,
            "agent_permission": 1,
            "customer_permission": 2,
            "custom_field_name": "SelectField_2",
            "title": "Radio Field",
            "content_type": "radio",
            "comment": null,
            "options": [
                {"0": "option 1"},
                {"1": "option 2"}
            ]
        },
        {
            "id": 3,
            "agent_permission": 1,
            "customer_permission": 2,
            "custom_field_name": "SelectField_3",
            "title": "Checkbox field",
            "content_type": "checkbox",
            "comment": null,
            "options": [
                {"0": "option 1"},
                {"1": "option 2"},
                {"2": "option 3"},
                {"3": "option 4"}
            ]
        }
    ]
}

Customer Bulk Import

This interface is used to create multiple customer information at once. Note: This method allows only one call per minute.

Request Method

POST /customers/batch_import_async

This feature is asynchronous, and up to 100 customers can be imported at a time. The interface returns code 1000, which only indicates that the import data has been successfully received and does not mean that the import is complete. If you are concerned about the import results, you need to configure the notification address. After the import is completed, a notification will be sent to the notification address, see Configure Notification Address for details.

Request Parameters (Request Body)

Parameter Name	Type	Required	Description
customers	Array	Yes	Array of customer information, see below

customers Elements

Parameter Name	Type	Required	Description	Limitations
nick_name	String	Yes	Name	Maximum length of 255 characters
description	String	No	Description	Maximum length of 255 characters
emails	Array	No	Email array
cellphones	Array	No	Phone number array
organization_id	Integer	No	Customer company ID
owner_id	Integer	No	Responsible customer service ID
owner_group_id	Integer	No	Responsible customer service group ID
level	String	No	Level, see Customer Data, default is "normal"
custom_fields	Object	No	Custom fields, see Customer Data
tags	String	No	Tags, separated by commas for multiple tags	Maximum length of 255 characters
open_api_token	String	No	External unique identifier	Maximum length of 255 characters
weixins	Array	No	WeChat information
weixin_minis	Array	No	WeChat Mini Program information

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success

Example

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": "test customer 2",
            "emails": ["customer2@sample.com", "customer2@qq.com"],
            "cellphones": ["13100000002", "13200000002"],
            "owner_id": 1,
            "owner_group_id": 1,
            "custom_fields": {
                "TextField_1": "Plain text content",
                "TextField_2": "Multiline text content 1\r\nMultiline text content 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"
                }
            ]
        }
    ]
}'

Response

{
    "code": 1000
}

Customer Bulk Export

This interface is used to export a large number of customer information. Supports filtering customers based on specified filters. Supports searching for customers by keyword.

Request Method

GET /customers/export The method of using this interface:

Use filter_id or query to call the interface, and the result will include the first batch of data and scroll_id.
After the data is processed, use the scroll_id returned from the previous call to call the interface again (note that you do not need to pass filter_id or query this time), and the result will include the second batch of data and a new scroll_id.
Repeat step 2 until the result returns an empty customers. Note:
For subsequent calls, you need to use the new scroll_id returned from the previous call. The scroll_id expires after 1 minute.
If the filter_id parameter is incorrect, it will query without filtering (i.e., return all customers).

Request Parameters (Query String)

Parameter Name	Type	Required	Description
filter_id	Integer	No	Customer filter ID, exports the filtered results of this filter
query	String	No	Keyword for customer search, exports the search results for this keyword
scroll_id	String	No	ID for obtaining the next batch of data, obtained from the result of the previous call

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
scroll_id	String	ID for obtaining the next batch of data
total	Integer	Total number of data
customers	Array	Customer list, see Customer Data

Note: The maximum number of customers retrieved in one go is 1000; when the number of customers in the return result is 0, it indicates the end of the export.

Example

# First call
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
# Follow-up call
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

Response

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

Data Structure - Customer

Customer

Attribute Name	Type	Description	Limitations
id	Integer	Unique identifier
nick_name	String	Name	Maximum length of 255 characters
level	String	Customer level
description	String	Description	Maximum length of 255 characters
owner_id	Integer	Responsible customer service ID
owner_group_id	Integer	Responsible customer service group ID
custom_fields	Object	Custom fields, see below for details
open_api_token	String	External unique identifier	Maximum length of 255 characters
organization_id	Integer	Customer company ID
organization_ids	Array(Integer)	Customer company list
default_organization_id	Integer	Default company ID
is_blocked	Boolean	Whether it is added to the blacklist
tags	Array	Tag list, see below for details
rich_tags	Array	Background color tag list, see below for details
email	String	Main email	Maximum length of 255 characters
other_emails	Array	Other email list
cellphones	Array	Contact phone list
weixins	Array	WeChat information
platform	String	Creation channel in Chinese (this field will be gradually abandoned)
source_channel	String	Customer source in Chinese
first_contact_at	Date-Time	First contact time
last_contact_at	Date-Time	Last contact time
first_contact_at_via_phone	Date-Time	First phone contact time
last_contact_at_via_phone	Date-Time	Last phone contact time
first_contact_at_via_im	Date-Time	First online customer service contact time
last_contact_at_via_im	Date-Time	Last online customer service contact time
weixin_minis	Array	WeChat Mini Program information
web_token	String	Customer web identifier	Maximum length of 255 characters
sdk_token	String	Customer SDK identifier	Maximum length of 255 characters

level

Value	Meaning
normal	General
vip	VIP

source_channel

Chinese Name	English Name
Manual Creation	manual
Phone In	callin
Phone Out	callout
WeChat	wechat
Weibo	weibo
Online Customer Service	web_im
API or SDK	api
Feedback Form	feedback
Email	mail
Bulk Import	import
Enterprise WeChat	qywx
WeChat Customer Service Number	weixin_kf
WeChat Mini Program	weixin_mini
Baidu BCP	baidu
Twitter	twitter
Facebook	facebook
Line	line
Whatsapp	whatsapp
Douyin Enterprise Number	tiktok
Video Customer Service	mpv

platform

Name	Description
email	Email
weibo	Weibo
wechat	WeChat
im	Instant Chat
call	Phone
feedback	Feedback Tag
hc	Help Center
manual_input	Manual Entry
api	API

rich_tags

Attribute Name	Type	Description
id	Integer	Tag ID
name	String	Tag Name
color	String	Tag Color
company_id	Integer	Company ID (Currently unused)

custom_fields

custom_fields example:

{
    "custom_fields": {
        "TextField_1": "Normal text content",                    // Normal text
        "TextField_2": "Multi-line text content1\r\nMulti-line text content2",  // Multi-line text
        "TextField_3": "2016-08-11",                              // Date
        "TextField_4": "14:44:36",                               // Time
        "TextField_5": "2017-05-03 14:44",                        // Date-Time
        "TextField_6": "https://www.sample.com",                 // Link
        "TextField_7": "13",                                     // Positive integer
        "TextField_8": "13.33",                                  // Numeric value
        "SelectField_1": ["0"],                                 // Dropdown list, Dropdown option 1
        "SelectField_2": ["0"],                                 // Radio button, Radio option 1
        "SelectField_3": ["0","3"]                               // Checkbox, Checkbox options 1, 4
    }
}

Merge Customer Information

This interface is used to merge the information of two customers.

Request Method

POST /customers/merge

Request Parameters (Query String)

Parameter Name	Type	Required	Description
from_type	String	Yes	from_type condition type, used to find the customer to be deleted after merging, see below for details
from_content	String	Yes	from_content condition content, used to find the customer to be deleted after merging
to_type	String	Yes	to_type condition type, used to find the customer to be retained after merging, see below for details
to_content	String	Yes	to_content condition content, used to find the customer to be retained after merging

Condition Types

Value	Meaning of content
email	Customer email
cellphone	Customer phone
customer_token	Customer external unique identifier
weixin_openid	Customer WeChat openid
weibo_openid	Customer Weibo openid
sdk_token	Customer SDK identifier
web_token	Customer web identifier
weixin_mini_openid	Customer Mini Program openid

Response Data

Attribute Name	Type	Description
code	Integer	Execution result code, 1000 represents success
id	Integer	ID of the customer retained after merging

Example

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"
}'

Response

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

Error Code Description

Error Code	Message Information	Exception:message Information	Description
429	API interface exceeds request limit	None	The request frequency of this interface exceeds the limit
2000	Unknown error	Missing custom field XXX	When the custom field is set to required, the parameter {custom_fields} is not filled in or does not meet the requirements
		param is missing or the value is empty: customer	No parameters in {customer}
		Email duplicate: customer id = XXX	The {email} parameter has been used by the customer with id XXX
		web_token duplicate: XXX	The {web_token} parameter has been used
		web_token format error: XXX	The format of the {web_token} parameter does not meet the requirements
		web_token must be a string	The {web_token} parameter must be a string
		Incorrect parameter format	The input parameter format is incorrect
		Verification failed: Email is invalid	The {email} parameter format is incorrect
		WeChat information (appid: XXX, openid: XXX) already exists in customer (id: XXX)	This WeChat information has been used by the customer with id XXX
		WeChat Mini Program information (appid: XXX, openid: XXX) already exists in customer (id: XXX)	This WeChat Mini Program information has been used by the customer with id XXX
		Verification failed: Phone XXX has been used	The phone number in {cellphones} has been used
		Company id does not exist	The {organization_id} parameter is incorrect
		Cannot find customer service	The {owner_id} parameter is incorrect
		Customer service exists but customer service group does not exist	Only the customer service id {owner_id} is entered, and the correct {owner_group_id} is also required
		Company does not have this customer service group	The {owner_group_id} parameter is incorrect
		Customer service does not belong to this customer service group	The parameters {owner_group_id} and {owner_id} do not match
		'xxx' is not a valid level	The value of the {level} parameter is not within the valid range
		undefined method `each' for "qweasd":String	The format of the {custom_fields} parameter is incorrect
		undefined method `each_with_index' for nil:NilClass	The {customer} parameter is an empty array or null, or this parameter is not filled in
		Import data is empty	The imported customer data is empty
		Import quantity (XXX) cannot exceed 100	The imported customer quantity exceeds the maximum limit of 100
	Merge customer failed: Cannot merge to self	None	When merging users, the two fields point to the same customer
	Invalid unique identifier type	None	Required parameter is not filled in
	Couldn't find Customer	None	Required parameter is not filled in
2005	The resource was not found	Couldn't find Customer	The provided parameter {content} did not find matching data
2060	Invalid unique identifier type	Invalid unique identifier type	The {type} parameter was not passed in
2062	Parameter error	Failed to get customer information	The {filter_id} or {scroll_id} parameter is incorrect
206211	Parameter page_size is invalid	None	The {page_size} parameter is not within the valid range
206201	Parameter page is invalid	None	The {page} parameter is not within the valid range