Custom status

Custom status is a feature that lets you create a custom connection status for agents and sub-categorize their availability status. This API returns a list of custom statuses agents can select when updating their connection status. Currently, custom status is supported for the Away status only.

Note: Admins can create and manage custom statuses in Agent status on the Settings page on Sendbird Dashboard.

Resource representation

The following table shows the list of properties in a custom status.

Property name	Type	Description
count	int	The total count of custom statuses in the application.
results[]	list	A list of custom statuses.
results.id	int	The unique ID of the custom status.
results.statusName	string	The name of the custom status. The maximum length is limited to 30 characters.
results.statusDescription	string	The description of the custom status.
results.statusType	string	The type of the custom status. Valid value is AWAY.
results.isRemoved	boolean	Indicates whether the custom status is removed.

Note: results.isRemoved = true means the status is archived in Dashboard.

Actions

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

Note: To find your application ID, sign in to your dashboard, go to the Overview page, and then check Application ID.

List of actions

Action	HTTP request
List custom statuses	`GET` /custom_statuses Retrieves a list of custom statuses in the application.

List custom statuses

Retrieves a list of custom statuses in the application. You can use this list when updating the connection status of an agent.

HTTP request

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

Note: If you are using Delight AI agent with Delight Desk, the endpoint for your API request should start with https://desk-api-{application_id}.svc.delight.ai/platform/v1 instead of https://desk-api-{application_id}.sendbird.com/platform/v1. For more details, refer to our Delight AI agent guide.

Parameters

The following table lists the supported parameters for this action.

Optional

Parameter name	Type	Description
is_removed	boolean	Filters custom statuses based on whether they are removed. To return only available statuses, set to `false`. (Default: `false`)
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)

Query string example

?limit=10&offset=20

Response

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

Status: 200 OK

{
  "count": 10,
  "next": "https://desk-api-{application_id}.sendbird.com/platform/v1/custom_statuses?limit=5&offset=5",
  "previous": null,
  "results": [
    {
      "id": 1,
      "statusName": "Break",
      "statusDescription": "Taking a break",
      "statusType": "AWAY",
      "isRemoved": false
    },
    {
      "id": 2,
      "statusName": "Training",
      "statusDescription": "Attending training session",
      "statusType": "AWAY",
      "isRemoved": false
    },
    {
      "id": 3,
      "statusName": "Team meeting",
      "statusDescription": "In a team meeting",
      "statusType": "AWAY",
      "isRemoved": false
    },
        ... # More custom statuses
  ]
}

List of response properties

Property name	Type	Description
count	int	The total count of custom statuses in the application.
next	string	The URL to retrieve the next page in the result set, or `null` if there is no next page.
previous	string	The URL to retrieve the previous page in the result set, or `null` if there is no previous page.
results[]	list	A list of custom statuses.

On this page

Resource representation Actions List custom statuses