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

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: 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 a member to a specific group.

Remove a member

DELETE /groups/{group_id}/membership
Removes a member from a specific group.

List groups

Retrieves a list of groups in the application.

HTTP request

Light Color Skin
Copy
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 before retrieving the next page in the result set. This is used to adjust the starting index of the next page. (Default: 0)

Query string example
Light Color Skin
Copy
?limit=5&offset=10

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "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

Light Color Skin
Copy
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 the target 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
Light Color Skin
Copy
{
    "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 a member to a specific group.

HTTP request

Light Color Skin
Copy
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 the target 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 the agent to add to the specified group.

Request body example
Light Color Skin
Copy
{
    "agentId": 2
}

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "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 a member from a specific group.

HTTP request

Light Color Skin
Copy
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 the target 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 the agent to remove from the specified group.

Request body example
Light Color Skin
Copy
{
    "agentId": 2
}

Response

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

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