Desk Platform API v1

Desk Platform API

Version 1

Group

Grouping agents and tickets help you manage Desk Platform more efficiently. With the Group API, you can retrieve a list of groups or view a specific group along with the agents belonging to it. Creating a new group is only available in Settings > Teams on the Sendbird Dashboard. Note that the term Group is referred to as Team on the dashboard.

Note: To see which group a specific ticket belongs to, use the Ticket API instead.

Resource representation

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

Property name	Type	Description
id	int	The unique ID of the group.
name	string	The name of the group.
key	string	The unique key of the group. The key can be a mix of lowercase letters, hyphens, underscores, or numbers.
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 group was created, in ISO 8601 format.
createdBy	string	The ID of an agent who created this group.
description	string	The description of the group.

Actions

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

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.

List of actions

Action	HTTP request
List groups	`GET` /groups Retrieves a list of groups in the application.
View a group	`GET` /groups/{group_id} Retrieves information on a specific group.
Add a member	`POST` /groups/{group_id}/membership Registers an agent as a member to a specific group.
Remove a member	`DELETE` /groups/{group_id}/membership Removes an agent from a specific group.

List groups

Retrieves a list of groups in the application.

HTTP request

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

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)

Query string example

?limit=5&offset=10

Response

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

Status: 200 OK

{
    "count": 65,
    "previous": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/groups?limit=5&offset=5",
    "next": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/groups?limit=5&offset=15",
    "results": [
        {
            "id": 13,
            "name": "CS Team",
            "key": "Customer Support",
            "project": 13,
            "createdAt": "2019-05-03T02:28:13.264936Z",
            "createdBy": 27,
            "description": "Customer support team"
        },
        ... # More groups
    ]
}

List of response properties

Property name	Type	Description
count	int	The total count of groups 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 groups.

View a group

Retrieves information on a specific group.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
group_id	int	Specifies the unique ID of a group.

Response

If successful, this action returns a group resource with the information of agents and tickets within the group in the response body.

Status: 200 OK

{
    "id": 77,
    "name": "DATW Team",
    "key": "DATW",
    "project": 13,
    "createdAt": "2019-05-03T02:28:13.264936Z",
    "createdBy": 27,
    "description": "Jeff's team",
    "members": [
        {
            "id": 28,
            "displayName": "Julia",
            "email": "julia_cake@sendbird.com",
            "photoThumbnailUrl": "https://file-staging.sendbird.com/profile_images/smile_julia.png"
        },
        ... # More agents
    ]
}

Add a member

Registers an agent as a member to a specific group.

HTTP request

POST https://desk-api-{application_id}.sendbird.com/platform/v1/groups/{group_id}/membership

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
group_id	int	Specifies the unique ID of a group.

Request body

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

Required

Property name	Type	Description
agentId	string	Specifies the unique ID of an agent to add to the specified group.

Request body example

{
    "agentId": 2
}

Response

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

Status: 200 OK

{
    "id": 1,
    "name": "solution team",
    "key": "solution",
    "project": 1,
    "createdAt": "2020-12-01T10:19:51.086740Z",
    "createdBy": 1,
    "description": null,
    "members": [
        {
            "displayName": "cindy",
            "email": "cindyyyy@sendbird.com",
            "photoThumbnailUrl": "",
            "connection": "OFFLINE",
            "connectionUpdatedAt": "2020-11-19T04:54:54.269263Z",
            "id": 1
        },
        {
            "displayName": "katherine",
            "email": "katherineeee@sendbird.com",
            "photoThumbnailUrl": "",
            "connection": "OFFLINE",
            "connectionUpdatedAt": "2020-12-01T04:54:41.156245Z",
            "id": 2
        }
    ]
}

Remove a member

Removes an agent from a specific group.

HTTP request

DELETE https://desk-api-{application_id}.sendbird.com/platform/v1/groups/{group_id}/membership

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
group_id	int	Specifies the unique ID of a group.

Request body

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

Required

Property name	Type	Description
agentId	string	Specifies the unique ID of an agent to remove from the specified group.

Request body example

{
    "agentId": 2
}

Response

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

Status: 200 OK

{
    "id": 1,
    "name": "solution team",
    "key": "team",
    "project": 1,
    "createdAt": "2020-12-01T10:19:51.086740Z",
    "createdBy": 1,
    "description": null,
    "members": [
        {
            "displayName": "tree",
            "email": "treeeee@sendbird.com",
            "photoThumbnailUrl": "",
            "connection": "OFFLINE",
            "connectionUpdatedAt": "2020-11-19T04:54:54.269263Z",
            "id": 1
        }
    ]
}

On this page

Resource representation Actions List groups View a group Add a member Remove a member