Platform API
Desk Customer

Customer

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

Resource representation

Property nameTypeDescription

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}.
ActionHTTP 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
OptionalTypeDescription

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=50&offset=50&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": 166,
    "previous": null
    "next": "https://desk-api-{application_id}.sendbird.com/platform/v1/customers?limit=50&offset=50",
    "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 nameTypeDescription

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
RequiredTypeDescription

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
RequiredTypeDescription

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
RequiredTypeDescription

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
RequiredTypeDescription

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