Skip to main content
Desk / Platform API
Current version: v1
Desk Platform API v1
Desk Platform API
Desk
Platform API
Home
/
Desk
/
Platform API

Group

Grouping agents and tickets help you manage Desk Platform more efficiently. With the Grou* 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 nameTypeDescription

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

ActionHTTP 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 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 when receiving a response. The value of offset is also used as the starting index of each page. (Default: 0)

?limit=5&offset=10

Response

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

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

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 nameTypeDescription

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.

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

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 nameTypeDescription

agentId

string

Specifies the unique ID of an agent to add to the specified group.

{
    "agentId": 2
}

Response

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

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

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 nameTypeDescription

agentId

string

Specifies the unique ID of an agent to remove from the specified group.

{
    "agentId": 2
}

Response

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

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