Skip to main content
Desk / Platform API
Desk
Platform API
Home
/
Desk
/
Platform API

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

List of actions

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.

Optional
Parameter nameTypeDescription

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

List of response properties

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.

Required
Parameter nameTypeDescription

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.

Required
Property nameTypeDescription

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.

Required
Parameter nameTypeDescription

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.

Required
Property nameTypeDescription

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
Light Color Skin
Copy
{
    "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
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": "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\"}"
        }
    ]
}