Home

Desk

Platform API

Customer

The Customer API allows you to manage various attributes of each customer.

Resource representation

Property name	Type	Description
id	int	The unique ID of the customer.
sendbirdId	string	The user ID of the customer which is either identical with the `user_id` in Sendbird Chat platform or integrated with the account in the social media but not identical.
channelType	string	A channel type that indicates which channel the customer comes from. Valid values are SENDBIRD, FACTBOOK_PAGE, TWITTER_USER, INSTAGRAM_USER, and WHATSAPP_USER.
project	int	The unique ID of a Desk project where the agent belongs. Desk projects have their own corresponding Sendbird application on a one-to-one basis.
createdAt	string	The date and time when the customer was created, in ISO 8601 format.
displayName	string	The name of the customer displayed in the Sendbird Dashboard. It is identical with the `nickname` in Sendbird Chat platform when the customer came from it.
photoThumbnailUrl	string	The URL of the customer's profile image.
customFields[]	array	An array of key-value custom fields that indicates additional information about the customer. This property can have up to 20 custom fields.

Actions

API endpoints are relative to the base URL allocated to your application. In this page, the /customers endpoint refers to https://desk-api-{application_id}.sendbird.com/platform/v1/customers.

Note: If you want to know your application ID, sign in to your dashboard, go to the Settings > Application > General, and then check the Application ID.

It's recommended that the parameter values in API URLs be urlencoded, such as {customer_id}.

Action	HTTP request
List customers	`GET` /customers Retrieves a list of customers registered in the application.
View a customer	`GET` /customers/{customer_id} Retrieves information on a specific customer.
Create a customer	`POST` /customers Creates a customer.
Update custom fields of a customer	`PATCH` /customers/{customer_id}/custom_fields Updates custom fields of a specific customer.

List customers

Retrieves a list of customers registered in the application.

HTTP request

Light Color Skin

Copy

GET https://desk-api-{application_id}.sendbird.com/platform/v1/customers

Parameters

The following table lists the parameters that this action supports.

Parameters

Optional	Type	Description
limit	int	Specifies the number of results to return per page. Acceptable values are 1 to 500, inclusive. (Default: 50)
offset	int	Specifies the number of results to skip before retrieving the next page in the result set. This is used to adjust the starting index of the next page. (Default: 0)
sendbird_id	string	Specifies the user ID of the target customer including IDs in Sendbird Chat platform and social media.

Query string example

Light Color Skin

Copy

?limit=5&offset=10&sendbird_id=summer

Response

If successful, this action returns a list of customer resources in the response body.

Status: 200 OK

Light Color Skin

Copy

{
    "count": 34,
    "previous": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/customers?limit=5&offset=5&sendbird_id=summer", 
    "next": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/customers?limit=5&offset=15&sendbird_id=summer",
    "results": [
        {
            "id": 680,
            "displayName": "Cindy Kim",
            "sendbirdId": "cindyyy",
            "channelType": "SENDBIRD",
            "project": 13,
            "createdAt": "2019-03-12T05:25:35.055635Z",
            "memo": null,
            "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/leave_vacation.png",
            "customFields": []
        },
        ... # More customers 
    ]
}

Property name	Type	Description
count	int	The total count of customers registered in the application.
previous	string	The URL to retrieve the previous page in the result set.
next	string	The URL to retrieve the next page in the result set.
results[]	list	A list of customers.

View a customer

Retrieves information on a specific customer.

HTTP request

Light Color Skin

Copy

GET https://desk-api-{application_id}.sendbird.com/platform/v1/customers/{customer_id}

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
customer_id	int	Specifies the unique ID of the target customer.

Response

If successful, this action returns a customer resource in the response body.

Create a customer

Creates a new customer in Desk who already has an ID in Sendbird Chat platform.

HTTP request

Light Color Skin

Copy

POST https://desk-api-{application_id}.sendbird.com/platform/v1/customers

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
sendbirdId	string	Specifies the Sendbird user ID of a customer to create.

Request body example

Light Color Skin

Copy

{
    "sendbirdId": "Cindy"
}

Response

If successful, this action returns a customer resource in the response body.

Update custom fields of a customer

Updates custom fields of a specific customer.

HTTP request

Light Color Skin

Copy

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/customers/{customer_id}/custom_fields

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
customer_id	int	Specifies the unique ID of the target customer.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties

Required	Type	Description
customFields	JSON string	Specifies a `JSON` string of one or more key-value custom fields to add or update. The key must not have a comma (,) and its length is limited to 20 characters. The value must be a string and its length is limited to 190 characters. This property can have up to 20 custom fields. New key-value items in the property are added when there are no items with the keys. The existing fields are updated with new values when there are already items with the keys.

Request body example

Light Color Skin

Copy

{
    "customFields": "{\"gender\":\"female\",\"country\":\"South Korea\"}"
}

Response

If successful, this action returns a customer resource with the updated custom fields in the response body.

Status: 200 OK

Light Color Skin

Copy

{
    "id": 680,
    "displayName": "Cindy Kim",
    "sendbirdId": "cindyyy",
    "channelType": "SENDBIRD",
    "project": 13,
    "createdAt": "2019-03-12T05:25:35.055635Z",
    "memo": null,
    "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/smile_cindy.png",
    "customFields": [
        {
            "id": 240,
            "key": "gender",
            "value": "female"
        },
        {
            "id": 241,
            "key": "country",
            "value": "South Korea"
        }
    ]
}

Agent

Connection logs

Ticket

ON THIS PAGE

List customers View a customer Create a customer Update custom fields of a customer