Agent

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

Resource representation

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

datetime

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

datetime

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

Retrieve a list of an agent's connection logs

GET /agents/{agent_id}/connection_logs
Retreives 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

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

Parameters

The following table lists the parameters that this action supports.

Parameters
OptionalTypeDescription

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=10&offset=20

Response

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

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

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

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

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

Light Color Skin
Copy
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.

Parameters
RequiredTypeDescription

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.

Request body example
Light Color Skin
Copy
{
    "connection": "ONLINE"
}

Response

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


Retrieve a list of an agent's connection logs

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

HTTP request

Light Color Skin
Copy
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.

Parameters
RequiredTypeDescription

agent_id

int

Specifies the unique ID of the target agent.

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

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "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
            "fromConnection": 1,
            "toConnection": 1,
            "durationTime": "sendbird_desk_agent_id_***",
            "createdAt": "2019-07-18T09:13:44.846926Z",
            "createdBy": 27 
        },
        ... # More connection logs 
    ]
}
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

Light Color Skin
Copy
GET https://desk-api-{app_id}.sendbird.com/platform/v1/agents/{agent_id}/assigned_ticket_counts

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

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.

Light Color Skin
Copy
{
    "ACTIVE": 2,
    "IDLE": 0
}

Get number of an agent’s closed tickets

Retrieves the number of closed tickets of a specific agent.

HTTP request

Light Color Skin
Copy
GET https://desk-api-{app_id}.sendbird.com/platform/v1/agents/{agent_id}/closed_ticket_counts

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

agent_id

int

Specifies the unique ID of the target agent.

start_date

datetime

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

datetime

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
Light Color Skin
Copy
?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.

Light Color Skin
Copy
{
    "CLOSED": 34
}