Home
/
Desk
/
Platform API

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 nameTypeDescription

id

int

A unique identifier 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 and INACTIVE.

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

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

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 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)

?limit=10&offset=20

Response

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

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

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 nameTypeDescription

agent_id

int

Specifies the unique ID of the target agent.

Response

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


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 nameTypeDescription

agent_id

int

Specifies the unique ID of the target agent.

Request body

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

Properties
RequiredTypeDescription

connection

string

Specifies the connection status of the agent to update. Acceptable values are:
- 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 the 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

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 nameTypeDescription

agent_id

int

Specifies the unique ID of the target agent.

Request body

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. A 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

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

agent_id

int

Specifies the unique ID of the target agent.

Response

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

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

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 nameTypeDescription

agent_id

int

Specifies the unique ID of the target agent.

Response

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

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 nameTypeDescription

agent_id

int

Specifies the unique ID of the target 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

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

{
    "CLOSED": 34
}