Desk / Platform API
Desk Platform API v1
Desk Platform API
Desk
Platform API
Version 1
Home
/
Desk
/
Platform API

Agent

Copy link

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

Copy link

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

Property nameTypeDescription

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

Copy link
  • 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

Copy link
ActionHTTP 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

Copy link

Retrieves a list of agents registered in the application.

HTTP request

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

Parameters

Copy link

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)

email

string

Specifies the email address of an agent to retrieve.

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

Response

Copy link

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

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

Copy link
Property nameTypeDescription

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

Copy link

Retrieves information on a specific agent.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

agent_id

int

Specifies the unique ID of an agent.

Response

Copy link

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

Update agent status

Copy link

Updates the status of a specific agent.

HTTP request

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

Parameters

Copy link

The following table lists the parameter that this action supports.

Required
Parameter nameTypeDescription

agent_id

int

Specifies the unique ID of an agent.

Request body

Copy link

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

Properties
RequiredTypeDescription

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.

{
    "status": "ACTIVE"
}

Response

Copy link

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

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

Copy link

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

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

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

Copy link

Updates the connection status of a specific agent.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

agent_id

int

Specifies the unique ID of an agent.

Request body

Copy link

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

Properties
RequiredTypeDescription

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.

OptionalTypeDescription

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.

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

Response

Copy link

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

Cancel assignments

Copy link

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

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

agent_id

int

Specifies the unique ID of an agent.

Request body

Copy link

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

Optional
Property nameTypeDescription

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.

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

Response

Copy link

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

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

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

Copy link

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

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

agent_id

int

Specifies the unique ID of an agent.

Response

Copy link

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

{
    "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,
            "durationTime": "sendbird_desk_agent_id_***",
            "createdAt": "2019-07-18T09:13:44.846926Z",
            "createdBy": 27
        },
        ... # More connection logs
    ]
}

List of response properties

Copy link
Property nameTypeDescription

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

Copy link

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

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

agent_id

int

Specifies the unique ID of an agent.

Response

Copy link

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

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

Get number of an agent’s closed tickets

Copy link

Retrieves the number of closed tickets of a specific agent.

HTTP request

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

Parameters

Copy link

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

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.

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

Response

Copy link

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

{
    "CLOSED": 34
}