Desk Platform API v1

Desk Platform API

Version 1

Agent

Agents can support your customers by handling inquiries and conversations on Sendbird Desk. Using the Agent API, you can manage various attributes of each agent.

Note: Inviting and adding a new agent is only available on the Sendbird Dashboard. To invite a new member, go to Organization settings > Members and send an invitation with the Desk Agent or Desk Admin role. After sending the invitation, all invited agents can be managed on Agents.

Resource representation

The following table shows the list of properties in an agent resource.

Property name	Type	Description
id	int	The unique ID of the agent.
displayName	string	The nickname of the agent. The maximum length is limited to 100 characters.
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.
user	string	The unique user ID of the agent.
sendbirdId	string	The unique ID of the agent used in Sendbird Chat platform. The maximum length is limited to 100 characters.
role	string	Indicates whether the agent is admin or not. Valid values are ADMIN and AGENT.
createdAt	string	The date and time when the agent was created, in ISO 8601 format.
status	string	Indicates whether the agents' account is activated. Valid values are ACTIVE, INACTIVE, PAUSED. PAUSED is only applicable to virtual agents, also known as bots.
connection	string	The connection status of the agent. Valid values are ONLINE, OFFLINE, and AWAY.
email	string	The email address of the agent.
photoThumbnailUrl	string	The profile image URL of the agent.
connectionUpdatedAt	string	The date and time of the agent's latest connection status update, in ISO 8601 format.
tier	string	The level of the agent. Valid values are INTERMEDIATE and EXPERT. (Default: INTERMEDIATE)

Actions

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

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

List of actions

Action	HTTP request
List agents	`GET` /agents Retrieves a list of agents registered in the application.
View an agent	`GET` /agents/{agent_id} Retrieves information on a specific agent.
Update the connection status of an agent	`PATCH` /agents/{agent_id}/connection Updates the connection status of a specific agent.
Cancel assignments	`POST` /agents/{agent_id}/cancel_assignments Cancels assignment of tickets from a specific agent.
Retrieve a list of an agent's connection logs	`GET` /agents/{agent_id}/connection_logs Retrieves a list of a specific agent's connection logs.
Get number of an agent’s assigned tickets	`GET` /agents/{agent_id}/assigned_ticket_counts Retrieves the number of an agent’s assigned tickets.
Get number of an agent’s closed tickets	`GET`/agents/{agent_id}/closed_ticket_counts Retrieves the number of an agent’s closed tickets.

List agents

Retrieves a list of agents registered in the application.

HTTP request

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

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)
email	string	Specifies the email address of an agent to retrieve.

Query string example

?limit=10&offset=20&email=summer_agent@sendbird.com

Response

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

Status: 200 OK

{
    "count": 40,
    "previous": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/agents?limit=10&offset=10",
    "next": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/agents?limit=10&offset=30",
    "results": [
        {
            "id": 1,
            "displayName": "Summer",
            "project": 1,
            "user": 1,
            "sendbirdId": "sendbird_desk_agent_id_***",
            "role": "AGENT",
            "createdAt": "2018-03-28T08:53:54.222766Z",
            "status": "ACTIVE",
            "connection": "ONLINE",
            "email":"summer_agent@sendbird.com",
            "photoThumbnailUrl":"https://sendbird.com/**.png",
            "connectionUpdatedAt": "2019-11-13T09:03:13.060232Z",
            "tier": "EXPERT"
        },
        ... # More agents
    ]
}

List of response properties

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

View an agent

Retrieves information on a specific agent.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
agent_id	int	Specifies the unique ID of an agent.

Response

If successful, this action returns an agent resource in the response body.

Update agent status

Updates the status of a specific agent.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/agents/{agent_id}/status

Parameters

The following table lists the parameter that this action supports.

Required

Parameter name	Type	Description
agent_id	int	Specifies the unique ID of an agent.

Request body

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

Properties

Required	Type	Description
status	string	Specifies the agent's status to update to. Acceptable values are the following: - ACTIVE: the agent is active. - INACTIVE: the agent is inactive. - PAUSED: the agent's activity is paused temporarily.

Request body example

{
    "status": "ACTIVE"
}

Response

If successful, this action returns an agent resource in the response body.

Status: 200 OK

{
    "id": 1,
    "displayName": "Anna",
    "project": 2296,
    "user": 2875,
    "sendbirdId": "sendbird_desk_agent_id_***",
    "role": "AGENT",
    "createdAt": "2018-03-28T08:53:54.222766Z",
    "status": "ACTIVE",
    "connection": "ONLINE",
    "email":"anna_agent@sendbird.com",
    "photoThumbnailUrl":"https://sendbird.com/**.png",
    "connectionUpdatedAt": "2019-11-13T09:03:13.060232Z",
    "tier": "EXPERT"
}

Error

In the case of an error, an error object like below is returned. See the error code table for more details.

Status: 400 Bad Request

{
    "message": "The status to be updated isn't specified.",
    "code": 400105,
    "error": true
}

Error code	Error message	Description
deskp400105	The status to be updated isn't specified.	The required `status` parameter isn't specified in the request body.
deskp400105	The value of status must be one of the following: `ACTIVE`, `INACTIVE`, `PAUSED`.	The specified value of `status` is invalid.
deskp400604	The status of a bot agent can't be updated.	The agent is a bot agent.
deskp400605	The agent's current {agent.status} status can't be changed.	The current agent status can't be changed to the specified value of `status`.

Update the connection status of an agent

Updates the connection status of a specific agent.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/agents/{agent_id}/connection

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
agent_id	int	Specifies the unique ID of an agent.

Request body

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

Properties

Required	Type	Description
connection	string	Specifies the connection status of an agent. Acceptable values are the following: - ONLINE: the agent is online. - OFFLINE: the agent is offline. - AWAY: the agent is away during the working hours.

Optional	Type	Description
groupKeyForTransfer	string	Specifies the unique key of a group to transfer an agent's active and idle tickets when their status changes to OFFLINE or AWAY. If not specified, tickets are transferred to the Default team.

Request body example

{
    "connection": "ONLINE",
    "groupKeyForTransfer": "TW"
}

Response

If successful, this action returns an agent resource with the updated connection status in the response body.

Cancel assignments

Cancels assignment of tickets from a specific agent. When the tickets are unassigned from the agent, their status changes to Pending. Then, they are assigned to another available agent within the current or specified team based on the auto ticket routing function.

Note: When a ticket is unassigned from a bot, the handover message is automatically sent to a customer. You can customize your handover message using the Bot API or in Settings > Bots on your dashboard.

HTTP request

POST https://desk-api-{application_id}.sendbird.com/platform/v1/agents/{agent_id}/cancel_assignments

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
agent_id	int	Specifies the unique ID of an agent.

Request body

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

Optional

Property name	Type	Description
groupKey	string	Specifies the unique key of a group to transfer both active and idle tickets that are unassigned from the agent. The value of DEFAULT is given for tickets transferred to the Default team because only the Default team doesn't have a team key. If this property isn't specified, tickets remain in their current teams and only the assignment of the agent's active tickets is canceled.

Request body example

{
    "groupKey": "tw-team"   // To transfer tickets to the Default team, use DEFAULT.
}

Response

If successful, this action returns information on the unassigned tickets in the response body.

Status: 200 OK

{
    "unassignedTickets": [1, 2, 3],
    "groupKey": "tw-team"
}

Property name	Type	Description
unassignedTickets	array of integers	The unique IDs of tickets whose assignment is successfully canceled.
groupKey	string	The unique key of a group where the tickets are transferred.

Retrieve a list of an agent's connection logs

Retrieves a list of a specific agent's connection logs.

HTTP request

GET https://desk-api-{application_id}.sendbird.com/platform/v1/agents/{agent_id}/connection_logs

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
agent_id	int	Specifies the unique ID of an agent.
start_date	string	Specifies the start date of the logs to retrieve, in YYYY-MM-DD format.
end_date	string	Specifies the end date of the logs to retrieve, in YYYY-MM-DD format.

Response

If successful, this action returns a list of an agent's connection log resources in the response body.

Status: 200 OK

{
    "count": 1251,
    "previous": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/agents/23/connection_logs?limit=10&offset=10",
    "next": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/agents/23/connection_logs?limit=10&offset=30",
    "results": [
        {
            "id": 1,        // connection log ID
            "agent": 27,    // agent ID
            "prevStatus": 1,
            "currentStatus": 1,
            "reason": "Break",
            "durationTime": "sendbird_desk_agent_id_***",
            "createdAt": "2019-07-18T09:13:44.846926Z",
            "createdBy": 27
        },
        ... # More connection logs
    ]
}

List of response properties

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

Get number of an agent’s assigned tickets

Retrieves the number of ACTIVE and IDLE tickets of a specific agent.

HTTP request

GET https://desk-api-{application_id}.sendbird.com/platform/v1/agents/{agent_id}/assigned_ticket_counts

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
agent_id	int	Specifies the unique ID of an agent.

Response

If successful, this action returns the numbers of ACTIVE and IDLE tickets of a specific agent.

Status: 200 OK

{
    "ACTIVE": 2,
    "IDLE": 0
}

Get number of an agent’s closed tickets

Retrieves the number of closed tickets of a specific agent.

HTTP request

GET https://desk-api-{application_id}.sendbird.com/platform/v1/agents/{agent_id}/closed_ticket_counts

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
agent_id	int	Specifies the unique ID of an agent.
start_date	string	Specifies a starting date and time that restricts the search scope to retrieve tickets closed between start_date and end_date, in ISO 8601 format.
end_date	string	Specifies an ending date and time that restricts the search scope to retrieve tickets closed between start_date and end_date, in ISO 8601 format.

Query string example

?start_date=2020-10-01&end_date=2020-10-20

Response

If successful, this action returns the number of closed tickets of a specific agent.

Status: 200 OK

{
    "CLOSED": 34
}

On this page

Resource representation Actions List agents View an agent Update agent status Update the connection status of an agent Cancel assignments Retrieve a list of an agent's connection logs Get number of an agent's assigned tickets Get number of an agent's closed tickets