Desk Platform API v1

Desk Platform API

Version 1

Customer

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

Resource representation

The following table shows the list of properties in a customer resource.

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, FACEBOOK_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}.

List of actions

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

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

Parameters

The following table lists the parameters that this action supports.

Optional

Parameter name	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 when receiving a response. The value of `offset` is also used as the starting index of each 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

?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

{
    "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
    ]
}

List of response properties

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

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
customer_id	int	Specifies the unique ID of a 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

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.

Required

Property name	Type	Description
sendbirdId	string	Specifies the Sendbird ID of a customer.

Request body example

{
    "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

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.

Required

Parameter name	Type	Description
customer_id	int	Specifies the unique ID of a customer.

Request body

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

Required

Property name	Type	Description
customFields	JSON string	Specifies a `JSON` string of one or more key-value custom fields to add or update. The specified key must be registered as a custom field in Settings > Customer fields of your dashboard beforehand. The length of key and value is limited to 20 and 190 characters, respectively. New values are added for the keys without values, or they will be updated if the specified key already has its value. When entering URLs for the link data type, it's recommended to start the URL with http:// or https://.

Request body example

{
    "customFields": "{
        \"gender\":\"female\",          // Dropdown
        \"age\": 27,                    // Integer
        \"country\":\"South Korea\",    // Text
        \"order-list\":\"{\\\"url\\\":\\\"https://sendbird.com/customer_cindy\\\",\\\"text\\\":\\\"Customer info\\\"}\" // Link
    }"
}

Response

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

Status: 200 OK

{
    "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": "age",
            "value": "27"
        },
        {
            "id": 242,
            "key": "country",
            "value": "South Korea"
        },
        {
            "id": 243,
            "key": "order-list",
            "value": "{\"text\": \"Customer info\", \"url\": \"https://sendbird.com/customer_cindy\"}"
        }
    ]
}

On this page

Resource representation Actions List customers View a customer Create a customer Update custom fields of a customer