Desk Platform API v1

Desk Platform API

Version 1

Ticket

With the Ticket API, you can manage inquiries from your customers. When a new ticket is submitted, your agents and customers can start a conversation within it.

Resource representation

The following table shows the list of properties in a ticket resource.

Property name	Type	Description
id	int	The unique ID of the ticket.
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.
channelName	string	The name of the ticket.
channelUrl	string	The channel URL of the ticket from Sendbird Chat platform. The value of tickets from social networks will be generated arbitrarily by Desk.
createdAt	string	The date and time when the ticket was created, in ISO 8601 format.
closedAt	string	The date and time when the ticket was closed, in ISO 8601 format.
issuedAt	string	The date and time when the customer sent the first message, in ISO 8601 format.
durationTime	int	The time in seconds taken from a customer's first message to ticket closing.
pendingTime	int	The time in seconds taken from a customer's first message to ticket assignment.
conversationTime	int	The time in seconds taken from a customer's first message to the last message of the conversation.
customer	nested object	An object that contains the information of the customer.
status2	string	The status of the ticket. This property has been updated from the previous version status to be consistent with the ticket status on the Sendbird Dashboard. Valid values are limited to the following: - INITIALIZED: tickets whose conversation has been started with welcome messages, but when there is no reply from the corresponding customer. - PROACTIVE: tickets whose conversation has been started with proactive messages, but when there is no reply from the corresponding customer. - PENDING: tickets that haven't been assigned to any agent yet. - ACTIVE: tickets that are assigned to agents and under the interactions. - CLOSED: closed tickets whose interaction between the agent and customer is ended. - WORK_IN_PROGRESS: tickets that are yet to be closed for any number of reasons but which can be ACTIVE once the conversation between the agent and customer is started. - IDLE: tickets whose customer hasn't replied for a set amount of time after the agent's last response.
closeStatus	string	The reason why the ticket has been closed. Valid values are limited to the following: - NOT_CLOSED: indicates the ticket is not closed yet. - CLOSED_BY_SYSTEM: indicates the ticket was closed by the API. - CLOSED_BY_CUSTOMER: indicates the ticket was closed by the customer. - CLOSED_BY_ADMIN: indicates the ticket was closed by an admin. - CLOSED_BY_AGENT: indicates the ticket was closed by an agent. - CLOSED_BUT_NOT_DEFINED (deprecated): indicates the closed ticket but the subject who closed it is unknown.
recentAssignment	nested object	The detailed information about the last assignment.
closeComment	string	The comment left for ticket closing.
closeMessage	string	The message for ticket closing, which is sent instead of the default closing message set in Settings > Triggers of your dashboard.
info	string	The information of a ticket such as subject and the requester given upon its creation.
messageCount	int	The total count of the messages in the ticket.
lastMessage	string	The last message of the ticket.
lastMessageSender	string	The sender of the last message. Valid values are CUSTOMER, AGENT, and PLATFORM.
lastMessageAt	string	The date and time when the last message was sent, in ISO 8601 format.
lastUserMessageSender	string	The sender of the last text message except for the admin messages from Desk Platform. Valid values are CUSTOMER and AGENT.
lastUserMessageAt	string	The date and time when the customer sent the last message, in ISO 8601 format.
updatedAt	string	The date and time when the ticket information was last updated, in ISO 8601 format.
firstAssignmentToCloseTime	int	The time in seconds taken from the first assignment of a ticket to ticket closing.
firstResponseTime	int	The time in seconds taken from a customer’s first message to an agent’s first response.
channelType	string	A channel type that indicates which channel the ticket belongs to. Valid values are SENDBIRD, SENDBIRD_IOS, SENDBIRD_ANDROID, SENDBIRD_JAVASCRIPT, FACEBOOK_CONVERSATION, FACEBOOK_FEED, TWITTER_STATUS, TWITTER_DIRECT_MESSAGE_EVENT, INSTAGRAM_COMMENT, and WHATSAPP_MESSAGE.
data	string	The information related to tickets from social networks.
lastSeenAt	int	The timestamp when the customer first read the last message in the ticket, in Unix millisecond. The value of 0 indicates the customer hasn't read the last message yet. This property is applicable for tickets from Facebook only.
group	nested object	The group which this ticket belongs to.
customFields[]	array	An array of key-value custom fields that indicates additional information about the ticket. This property can have up to 20 custom fields.
customerSatisfactionScore	int	The customer satisfaction score. Valid values are 1 to 5, inclusive.
customerSatisfactionComment	string	The feedback from a customer about the support within the ticket.
priority	string	The priority of the ticket. Valid values are LOW, MEDIUM, HIGH, and URGENT. When it comes to ticket assignment with the auto ticket routing function, a ticket with a higher priority takes precedence over others.
priorityValue	int	The priority value of the ticket. Valid values are 10, 20, 30, and 40, which indicate Low, Medium, High, and Urgent in the `priority`, respectively. The value can be set in increments of 10, and the higher the priority, the higher the value will be.
relatedChannel	nested object	The information of channels in Sendbird Chat platform that are related to this ticket.

Actions

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

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

List of actions

Action	HTTP request
List tickets	`GET` /tickets Retrieves a list of tickets all tickets in the application.
View a ticket	`GET` /tickets/{ticket_id} Retrieves information on a specific ticket.
Create a ticket	`POST` /tickets Creates a ticket.
Update a ticket	`PATCH` /tickets/{ticket_id} Updates a ticket's priority and URLs of the related channels.
Update custom fields of a ticket	`PATCH` /tickets/{ticket_id}/custom_fields Updates custom fields of a specific ticket.
Close a ticket	`PATCH` /tickets/{ticket_id}/close Closes a ticket.
Reopen a closed ticket	`PATCH` /tickets/{ticket_id}/reopen Reopens a closed ticket.
Transfer a ticket to an agent	`POST` /tickets/{ticket_id}/transfer Transfers tickets from an agent to another agent.
Transfer tickets to a group	`POST` /tickets/transfer_to_group Transfers tickets with a specific status to a specific team.
Cancel assignment of a ticket	`PATCH` /tickets/{ticket_id}/cancel Cancels assignment of a specific ticket from an agent.
Update CSAT data of a closed ticket	`PATCH` tickets/{ticket_id}/csat Updates a CSAT score and comment of a closed ticket.

List tickets

Retrieves a list of all tickets in the application.

HTTP request

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

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. Acceptable values are 0 to 10,000, inclusive. (Default: 0)
status2	string	Restricts the search scope to only retrieve tickets whose status matches the specified value. You can also specify multiple `status2` items like `status2=IDLE&status2=PENDING`. Acceptable values are limited to the following: - INITIALIZED: tickets whose conversation has been started with welcome messages, but when there is no reply from the corresponding customer. - PROACTIVE: tickets whose conversation has been started with proactive messages, but when there is no reply from the corresponding customer. - PENDING: tickets that haven't been assigned to any agent yet. - ACTIVE: tickets that are assigned to agents and under the interactions. - CLOSED: closed tickets whose interaction between the agent and customer is ended. - WORK_IN_PROGRESS: tickets that are yet to be closed for any number of reasons but which can be ACTIVE once the conversation between the agent and customer is started. - IDLE: tickets whose customer hasn't replied for a set amount of time after the agent's last response.
agent	string	Specifies the unique ID of an agent to restrict the search scope to only retrieve tickets assigned to a specific agent.
group	string	Restricts the search scope to only retrieve tickets assigned to the specified team.
sendbird_id	string	Restricts the search scope to only retrieve tickets submitted by a customer with a specified Sendbird ID.
q	string	Restricts the search scope to retrieve up to 100 tickets that match a specified keyword. The specified keyword is applied to the following: channel names, and customers' display names and Sendbird IDs. For example, `q=cindy` retrieves tickets whose channel name, or a customer's display name or Sendbird ID includes `cindy`.
assignment_status	string	Restricts the search scope to only retrieve tickets whose assignment status matches the specified value. Acceptable values are limited to the following: - NOT_RESPONDED: tickets whose assignee hasn’t responded yet. - RESPONDED: tickets whose assignee responded. - IDLE: tickets whose assignee responded, but when there is no reply from the corresponding customer for a set amount of time. Once the customer replies, its assignment status will be changed to NOT_RESPONDED.
channel_url	string	Restricts the search scope to only retrieve tickets related to a specified channel URL.
updated_since	date	Specifies a starting date that restricts the search scope to retrieve tickets that have been updated after the point, in YYYY-MM-DD format.
start_date	date	Specifies a starting date that restricts the search scope to retrieve tickets created between start_date and end_date, in YYYY-MM-DD format.
end_date	date	Specifies an ending date that restricts the search scope to retrieve tickets created between start_date and end_date, in YYYY-MM-DD format.
order	string	Specifies the method to sort a list of results. Acceptable values are limited to the following: - id (default): sorts by ticket ID in ascending order. - -id: sorts by ticket ID in descending order. - created_at: sorts by the time of ticket creation in ascending order. - -created_at: sorts by the time of ticket creation in descending order.

Query string example

?limit=20&offset=40

Response

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

Status: 200 OK

{
    "count": 523,
    "previous": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/tickets?limit=20&offset=20",
    "next": "https://desk-api-xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx.sendbird.com/platform/v1/tickets?limit=20&offset=60",
    "results":[
        {
            "id": 3351,
            "project": 13,
            "channelName": "Issue #818",
            "createdAt": "2020-03-21T06:52:51.374823Z",
            "channelUrl": "sendbird_group_channel_730883_973004c40cc0c881e603b61ba5dab3ce17a2a",
            "closedAt": "2020-03-21T07:16:14.995451Z",
            "issuedAt": "2020-03-21T06:52:55.701744Z",
            "durationTime": 36898079,
            "pendingTime": 0,
            "conversationTime": 36838815,
            "customer": {
                "id": 680,
                "sendbirdId": "hi_duskan",
                "channelType": "SENDBIRD",
                "project": 13,
                "createdAt": "2020-03-12T05:25:35.055635Z",
                "memo": null,
                "displayName": "Duskan",
                "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/profile_duskan.png",
                "customFields": []
            },
            "closeStatus": "CLOSED_BY_ADMIN",
            "recentAssignment": {
                "id": 8177,
                "assignedTicket": 3351,
                "agent": {
                    "id": 28,
                    "displayName": "Angel_Mike",
                    "project": 13,
                    "user": 13,
                    "sendbirdId": "sendbird_desk_agent_id_319bf388-3e97-4245-870e-2653f2e9ecb0",
                    "role": "AGENT",
                    "createdAt": "2020-03-12T05:30:35.504014Z",
                    "status": "ACTIVE",
                    "connection": "ONLINE",
                    "email": "[email protected]",
                    "photoThumbnailUrl": "https://file.sendbird.com/profile_images/mike_vacation.png",
                    "connectionUpdatedAt": "2020-08-13T04:31:28.653651Z",
                    "tier": "EXPERT"
                },
                "assignedAt": "2020-03-21T06:52:55.993589Z",
                "responsedAt": "2020-03-21T06:53:02.526407Z",   // This property will be deprecated soon. Use `respondedAt` instead.
                "respondedAt": "2020-03-21T06:53:02.526407Z",
                "endedAt": "2020-03-21T07:16:14.995469Z",
                "status": "IDLE",
                "responseTime": 5
            },
            "closeComment": "This idle ticket has been closed automatically by Sendbird Desk",
            "info": "{\"ticket\":{\"subject\":\"Issue #818\",\"requester\":{\"name\":\"Duskan\",\"email\":\"hi_duskan\"}}}",
            "messageCount": 6,
            "lastMessage": "This ticket is closed by sbdesk.",
            "lastMessageSender": "PLATFORM",
            "lastMessageAt": "2020-03-21T07:16:15.385722Z",
            "lastUserMessageSender": "AGENT",
            "lastUserMessageAt": "2020-03-21T07:14:11.284000Z",
            "lastMessageMembers": "[]",
            "updatedAt": "2020-02-14T02:16:57.646078Z",
            "lastMessagePayload": null,
            "firstAssignmentToCloseTime": 1399,
            "firstResponseTime": 590484,
            "channelType": "SENDBIRD",
            "data": "{}",
            "lastSeenAt": 0,
            "group": {
                "id": 51,
                "name": "Sales",
                "key": null,
                "project": 13,
                "createdAt": "2019-06-20T04:57:58.743091Z",
                "createdBy": 27,
                "description": "Sales related tickets are assigned to this time."
            },
            "customFields": [],
            "customerSatisfactionScore": null,
            "customerSatisfactionComment": null,
            "priority": "URGENT",
            "priorityValue": 40,
            "status2": "CLOSED",
            "relatedChannels": null
        },
        ... # More tickets
    ]
}

List of response properties

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

View a ticket

Retrieves information on a specific ticket.

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.

Response

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

Create a ticket

Creates a new ticket.

HTTP request

POST https://desk-api-{application_id}.sendbird.com/platform/v1/tickets

Request body

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

Properties

Required	Type	Description
channelName	string	Specifies the title of a ticket, which will be the group channel name in Sendbird Chat platform as well. Maximum length is 100 characters.
customerId	int	Specifies the unique ID of a customer which is different from sendbird_id in Sendbird Chat platform. This customerId can be retrieved by the Customer API's list customers action.

Optional	Type	Description
groupKey	string	Specifies the unique key of a group for ticket assignment. The key can be a mix of lowercase letters, hyphens, underscores, or numbers. When the request doesn't include this property, the ticket is assigned to a team according to the auto ticket routing function and the assignment rule. When the request has the `groupKey` without any value or with an invalid value specified, the created ticket is automatically assigned to the Default team.
customFields	JSON string	Specifies a `JSON` string of one or more key-value custom fields to add or update. The key must not have a comma (,) and its length is limited to 20 characters. The value must be a string and its length is limited to 190 characters. This property can have up to 20 custom fields.
priority	string	Specifies the priority of a ticket. Acceptable values are the following: LOW, MEDIUM, HIGH, and URGENT. When it comes to ticket assignment with the auto ticket routing function, a ticket with a higher priority takes precedence over others. (Default: MEDIUM)
relatedChannelUrls	string	Specifies a comma-separated string of one or more group channel URLs for reference, where the corresponding customer belongs. This property can have up to 3 group channel URLs.

Request body example

{
    "channelName": "Ticket for late delivery",
    "customerId": 156732,
    "groupKey": "cs-team",
    "customFields": "{\"string\":\"string\",\"integer\":100,\"dropdown\":\"option1\",\"link\":\"{\\\"url\\\": \\\"https://www.example.com\\\", \\\"text\\\": \\\"title\\\"}\"}",
    "priority": "HIGH",
    "relatedChannelUrls": "sendbird_desk_chat_25108471, sendbird_desk_chat_54852434, sendbird_desk_chat_48297842"
}

Response

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

Update a ticket

Updates a ticket's priority and URLs of the related channels.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.

Request body

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

Optional

Property name	Type	Description
priority	string	Specifies the priority of a ticket. Valid values are the following: LOW, MEDIUM, HIGH, and URGENT. When it comes to ticket assignment with the auto ticket routing function, a ticket with a higher priority takes precedence over others. (Default: MEDIUM)
relatedChannelUrls	string	Specifies the URLs of group channels in Sendbird Chat that are related to a ticket and where the customer belongs. Invalid URLs including URLs where the customer doesn't belong are ignored. URLs should be separate with commas, and up to three group channel URLs can be added per ticket.

Request body example

{
    "priority": "LOW",
    "relatedChannelUrls": "sendbird_group_channel_1,sendbird_group_channel_2"
}

Response

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

Status: 200 OK

{
    "id": 3351,
    "project": 13,
    "channelName": "issue #123",
    "createdAt": "2020-08-13T05:09:46.005856Z",
    "channelUrl": "sendbird_group_channel_3",
    "closedAt": null,
    "issuedAt": null,
    "durationTime": null,
    "pendingTime": null,
    "conversationTime": null,
    "customer": {
        "id": 681,
        "sendbirdId": "roy",
        "channelType": "SENDBIRD",
        "project": 13,
        "createdAt": "2019-03-12T05:45:33.808794Z",
        "memo": null,
        "displayName": "rocket_roy",
        "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/profile_smile_summer.png",
        "customFields": []
    },
    "closeStatus": "NOT_CLOSED",
    "recentAssignment": null,
    "closeComment": null,
    "info": null,
    "messageCount": null,
    "lastMessage": "I want to get a refund :(.",
    "lastMessageSender": "PLATFORM",
    "lastMessageAt": null,
    "lastUserMessageSender": null,
    "lastUserMessageAt": "2020-08-13T05:09:46.005898Z",
    "lastMessageMembers": "[]",
    "updatedAt": null,
    "lastMessagePayload": null,
    "firstAssignmentToCloseTime": null,
    "firstResponseTime": 590484,
    "channelType": "SENDBIRD",
    "data": "{}",
    "lastSeenAt": 0,
    "group": {
        "id": 72,
        "name": "FE_team",
        "key": "01010101010",
        "project": 13,
        "createdAt": "2020-01-28T07:10:34.844805Z",
        "createdBy": 27,
        "description": "Issues related to front engineering are assigned to this team."
    },
    "customFields": [
        {
            "id": 240,
            "key": "phone_number",
            "value": "0004-0005-0006"
        },
        {
            "id": 241,
            "key": "delivery_address",
            "value": "101, Samsung-dong, Gangnam-gu, Seoul"
        }
    ],
    "customerSatisfactionScore": null,
    "customerSatisfactionComment": null,
    "priority": "LOW",
    "priorityValue": 10,
    "status2": "INITIALIZED",
    "relatedChannels": "[{\"name\": \"Issue #001\", \"channel_url\": \"sendbird_group_channel1\"}, {\"name\": \"Issue #002\", \"channel_url\": \"sendbird_group_channel2\"}]"
}

Update custom fields of a ticket

Updates custom fields of a specific ticket.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/custom_fields

Parameters

The following table lists the parameters that this action supports.

Parameters

Required	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.

Request body

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

Properties

Required	Type	Description
customFields	JSON string	Specifies a `JSON` string of one or more key-value custom fields to add or update. The specified key must be registered as a custom field in Settings > Ticket fields of your dashboard beforehand. The length of key and value is limited to 20 and 190 characters, respectively. New values are automatically added for the keys without values, or they will be updated if the specified key already has its value. When entering URLs for the link data type, it's recommended to start the URL with http:// or https://.

Request body example

{
    "customFields": "{
        \"request-type\":\"refund\",    // Dropdown
        \"region\": 3,                  // Integer
        \"subject\":\"shoes\",          // Text
        \"order-list\":\"{\\\"url\\\":\\\"https://sendbird.com/orders\\\",\\\"text\\\":\\\"Track orders\\\"}\"  // Link
    }"
}

Response

If successful, this action returns a ticket resource with the updated custom fields in the response body.

Status: 200 OK

{
    "id": 3351,
    "project": 13,
    "channelName": "Pizza_delivery_delayed",
    "createdAt": "2020-08-13T05:09:46.005856Z",
    "channelUrl": "sendbird_group_channel_730883_973004c40cc0c881e603b61ba5dab3ce17a2a865",
    "closedAt": null,
    "issuedAt": null,
    "durationTime": null,
    "pendingTime": null,
    "conversationTime": null,
    "customer": {
        "id": 681,
        "sendbirdId": "tree_in_the_park",
        "channelType": "SENDBIRD",
        "project": 13,
        "createdAt": "2019-03-12T05:45:33.808794Z",
        "memo": null,
        "displayName": "tree",
        "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/profile_cherry-blossom-tree.png",
        "customFields": []
    },
    "closeStatus": "NOT_CLOSED",
    "recentAssignment": null,
    "closeComment": null,
    "info": null,
    "messageCount": null,
    "lastMessage": null,
    "lastMessageSender": "PLATFORM",
    "lastMessageAt": null,
    "lastUserMessageSender": null,
    "lastUserMessageAt": "2020-08-13T05:09:46.005898Z",
    "lastMessageMembers": "[]",
    "updatedAt": null,
    "lastMessagePayload": null,
    "firstAssignmentToCloseTime": null,
    "firstResponseTime": 590484,
    "channelType": "SENDBIRD",
    "data": "{}",
    "lastSeenAt": 0,
    "group": {
        "id": 72,
        "name": "CS_team",
        "key": "01010101010",
        "project": 13,
        "createdAt": "2020-01-28T07:10:34.844805Z",
        "createdBy": 27,
        "description": "Customer support related tickets are assigned to this team."
    },
    "customFields": [
        {
            "id": 240,
            "key": "request-type",
            "value": "refund"
        },
        {
            "id": 241,
            "key": "region",
            "value": 3
        },
        {
            "id": 242,
            "key": "subject",
            "value": "pizza"
        },
        {
            "id": 243,
            "key": "order-list",
            "value": "{\"text\": \"Track orders\", \"url\": \"https://sendbird.com/orders\"}"
        }
    ],
    "customerSatisfactionScore": null,
    "customerSatisfactionComment": null,
    "priority": "MEDIUM",
    "priorityValue": 20,
    "status2": "INITIALIZED",
    "relatedChannels": null
}

Close a ticket

Closes a specific ticket.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/close

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.

Request body

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

Optional

Property name	Type	Description
closeComment	string	Specifies the notes for ticket closing.
closeMessage	string	Specifies the message for ticket closing, which is sent instead of the default closing message set in Settings > Triggers of your dashboard.

Request body example

{
    "closeComment": "This issue has been resolved.",
    "closeMessage": "This ticket is closed. If you have any other questions, please create a new ticket."
}

Response

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

Status: 200 OK

{
    "id": 19371,
    "project": 1,
    "channelName": "Issue #001",
    "createdAt": "2020-08-03T12:57:12.618753Z",
    "channelUrl": "sendbird_group_channel_1",
    "closedAt": "2020-08-07T03:57:32.720074Z",
    "issuedAt": "2020-08-03T12:57:14.346761Z",
    "durationTime": 313218,
    "pendingTime": 0,
    "conversationTime": null,
    "customer": {
        "customerObject"
    },
    "closeStatus": "CLOSED_BY_PLATFORM_API",
    "recentAssignment": {
        "AssignmentObject"
    },
    "closeComment": "This issue has been resolved.",
    "info": "",
    "messageCount": 1,
    "lastMessage": "This ticket is automatically assigned to Cindy.",
    "lastMessageSender": "PLATFORM",
    "lastMessageAt": "2020-08-07T03:57:07.382000Z",
    "lastUserMessageSender": "CUSTOMER",
    "lastUserMessageAt": "2020-08-03T12:57:14.116000Z",
    "lastMessageMembers": "[]",
    "updatedAt": "2020-08-07T03:57:07.610750Z",
    "lastMessagePayload": null,
    "firstAssignmentToCloseTime": 313217,
    "firstResponseTime": 590484,
    "channelType": "SENDBIRD",
    "data": "{}",
    "lastSeenAt": 0,
    "group": {
        "groupObject"
    },
    "customFields": [],
    "customerSatisfactionScore": null,
    "customerSatisfactionComment": null,
    "priority": "MEDIUM",
    "priorityValue": 20,
    "status2": "CLOSED",
    "relatedChannels": null
}

Transfer a ticket to an agent

Transfers a ticket to another agent and change the ticket assignee. Only active and idle tickets can be transferred. If you wish to transfer a ticket to a bot agent, it's highly recommended you check the bot's canReceiveTransferredTickets property first.

HTTP request

POST https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/transfer

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_id	int	Specifies the ID of a ticket to transfer.

Request body

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

Property

Required	Type	Description
agentId	int	Specifies the ID of an agent who will be newly assigned to the ticket.

Optional	Type	Description
note	string	Specifies the reason why the ticket is transferred.

Request body example

{
    "agentId": 3566,
    "note": "a delivery issue; transfer to the shipping team" 
}

Response

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

Status: 200 OK

{
    "id": 9,
    "pastAssignment": {
        "id": 4099,
        "assignedTicket": 4909,
        "agent": {
            "id": 3565,
            "displayName": "Daniel",
            "project": 2300,
            "user": 3787,
            "sendbirdId": "",
            "role": "AGENT",
            "createdAt": "2022-11-23T16:06:44.213991Z",
            "status": "ACTIVE",
            "connection": "OFFLINE",
            "email": "[email protected]",
            "photoThumbnailUrl": "",
            "connectionUpdatedAt": null,
            "tier": "INTERMEDIATE"
        },
        "assignedAt": "2022-11-23T16:06:44.391556Z",
        "respondedAt": null,
        "endedAt": "2022-11-23T16:06:44.426722Z",
        "status": "NOT_RESPONSED",
        "unreadCount": 0,
        "responseTime": null
    },
    "currentAssignment": {
        "id": 4100,
        "assignedTicket": 4909,
        "agent": {
            "id": 3566,
            "displayName": "Sid",
            "project": 2300,
            "user": 3788,
            "sendbirdId": "",
            "role": "AGENT",
            "createdAt": "2022-11-23T16:06:44.386882Z",
            "status": "ACTIVE",
            "connection": "OFFLINE",
            "email": "[email protected]",
            "photoThumbnailUrl": "",
            "connectionUpdatedAt": null,
            "tier": "INTERMEDIATE"
        },
        "assignedAt": "2022-11-23T16:06:44.432639Z",
        "responsedAt": null,
        "endedAt": null,
        "status": "NOT_RESPONSED",
        "unreadCount": 1,
        "responseTime": null
    },
    "note": "a delivery issue; transfer to the shipping team",
    "transferredAt": "2022-11-23T16:06:44.436502Z"
}

List of response properties

Property name	Type	Description
id	int	The unique ID of the ticket that has been transferred.
transferredAt	string	The date and time when the ticket was transferred, in ISO 8601 format.
pastAssignment	nested object	The information of the ticket's previous assignment. When a ticket is transferred through an API request, the response contains information about prior assignment, such as a former assignee of the ticket.
currentAssignment	nested object	The information of the ticket's new assignment. When a ticket is transferred through an API request, the response contains information about new assignment, such as a current assignee of the ticket.
note	string	The statement about why the ticket was transferred.

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 agentId property is required.",
    "code": 400105,
    "error": true
}

Error code	Error message	Description
deskp400105	The agentId property is required.	The `agentId` value should be specified.
deskp400105	The note property is required.	Depending on your Ticket transfer setting under Settings > Desk > General on Sendbird Dashboard, `note` may be required for ticket transfer.
deskp400111	The value of agentId should be integer.	The specified `agentId` is in incorrect format.
deskp400111	Ticket status should be ACTIVE or IDLE.	Only active or idle tickets can be transferred.
deskp400111	The specified agentId is the current assignee. Enter different agentId.	The specified `agentId` should be different from the ID of the current assignee.
deskp400111	The bot specified in agentId does not support ticket transfer. Check the bot settings.	Ticket transfer to bots is effective only when a bot agent's `canReceiveTransferredTickets` is set to true.
deskp400111	Transfer is not supported for this ticket's channelType.	Ticket transfer to custom bots isn't possible for tickets submitted through some social media channels, such as Facebook post's comments, Instagram post's comments, and Twitter tweets. For FAQ bots, only the tickets submitted through in-app chat can be transferred to them.
deskp400201	The specified agent doesn’t exist.	The agent with the specified `agentId` doesn't exist.
deskp400603	Can't transfer. The agent already has the maximum number of active tickets.	The specified agent already has the maximum number of tickets set under Settings > Desk > Automation > Auto ticket routing on Sendbird Dashboard.
desk500500	An internal error has occurred.	An error occurred while processing the request.

Reopen a closed ticket

Reopens a closed ticket. However, tickets submitted through social media channels can only be reopened on the dashboard, not through this request.

Note: Tickets that have been closed more than 20 days prior to the request can't be reopened.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/{ticket_id}/reopen

Parameter

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

Parameter name	Type	Description
ticket_id	int	Specifies the ID of a ticket to reopen.

Response

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

Status: 200 OK

{
    "id": 208430,
    "project": 13,
    "channelName": "Issue #244",
    "createdAt": "2023-08-23T00:11:49.532276Z",
    "channelUrl": "sendbird_group_channel_123235026_6ba98d673545ee24f744dc2a7bc6f13dfc7a2ae1",
    "closedAt": null,
    "issuedAt": "2023-08-23T00:11:51.544152Z",
    "durationTime": null,
    "pendingTime": 0,
    "conversationTime": 180,
    "customer": {
        "id": 27951,
        "sendbirdId": "yj12",
        "channelType": "SENDBIRD",
        "project": 13,
        "createdAt": "2023-08-23T00:11:45.996352Z",
        "displayName": "yj12",
        "photoThumbnailUrl": "https://static.sendbird.com/sample/user_sdk/user_sdk_17.png"
    },
    "closeStatus": "NOT_CLOSED",
    "recentAssignment": {
        "id": 104268,
        "assignedTicket": 208430,
        "agent": {
            "id": 17355,
            "displayName": "Agent SDK",
            "project": 13,
            "user": 1956,
            "sendbirdId": "sendbird_desk_agent_id_f05ca0cc-f12b-49e2-9311-36897df411dd",
            "role": "AGENT",
            "createdAt": "2023-09-01T05:53:49.838490Z",
            "status": "ACTIVE",
            "connection": "OFFLINE",
            "email": "[email protected]",
            "photoThumbnailUrl": "",
            "connectionUpdatedAt": null,
            "tier": "INTERMEDIATE"
        },
        "assignedAt": "2023-09-01T07:43:12.276574Z",
        "responsedAt": null,
        "respondedAt": null,
        "endedAt": "2023-09-01T07:57:01.569795Z",
        "status": "NOT_RESPONSED",
        "unreadCount": 4,
        "responseTime": null
    },
    "closeComment": "",
    "info": "{\"ticket\":{\"subject\":\"Issue #244\",\"requester\":{\"name\":\"yj12\",\"email\":\"yj12\"}}}",
    "messageCount": 6,
    "lastMessage": "The ticket is closed by agent.!! .\n-\n-",
    "lastMessageSender": "PLATFORM",
    "lastMessageAt": "2023-09-01T07:57:01.853000Z",
    "lastUserMessageSender": "CUSTOMER",
    "lastUserMessageAt": "2023-08-23T00:14:52.264000Z",
    "lastMessageMembers": "[]",
    "updatedAt": "2023-09-20T08:34:02.406499Z",
    "lastMessagePayload": null,
    "firstAssignmentToCloseTime": 805509,
    "firstResponseTime": null,
    "channelType": "SENDBIRD_JAVASCRIPT",
    "data": "{}",
    "lastSeenAt": 0,
    "group": {
        "id": 51,
        "name": "Default",
        "key": null,
        "project": 13,
        "createdAt": "2019-12-30T04:57:58.743091Z",
        "createdBy": 27,
        "description": "Agents are added to this team as default. You can assign agents to other teams."
    },
    "customFields": [],
    "tags": [],
    "customerSatisfactionScore": null,
    "customerSatisfactionComment": null,
    "customerSatisfactionResponseAt": null,
    "customerSatisfactionSentAt": null,
    "priority": "MEDIUM",
    "priorityValue": 20,
    "status2": "PENDING",
    "relatedChannels": null,
    "lastAssignedAgent": 17355
}

Transfer tickets to a group

Transfers tickets with a specific status to a specific team.

HTTP request

POST https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/transfer_to_group

Request body

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

Required

Property name	Type	Description
tickets	array of integers	Specifies one or more IDs of pending tickets for transfer. Up to 100 ticket IDs can be specified.
status	string	Specifies the status of tickets for transfer. An acceptable value is PENDING.
groupKey	string	Specifies the unique key of a group for ticket transfer. The key can be a mix of lowercase letters, hyphens, underscores, or numbers.

Request body example

{
    "tickets": [1, 2, 3, 4],
    "status": "PENDING",
    "groupKey": "cs-team"
}

Response

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

Status: 200 OK

{
    "transferredTickets": [1, 2, 3],
    "status": "PENDING"
}

List of response properties

Property name	Type	Description
transferredTickets	array of integers	The unique IDs of successfully transferred tickets.
status	string	The status of transferred tickets. The valid value is PENDING.

Cancel assignment of a ticket

Cancels assignment of a specific ticket from an agent. When a ticket is unassigned from an agent, its status changes to Pending. Then, it is assigned to another available agent within the 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 of your dashboard.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/cancel

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.

Request body

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

Optional

Property name	Type	Description
group	int	Specifies the unique key of a group. The ticket is reassigned to this group and then changes its status to Pending.

Request body example

{
    "group": 51
}

Response

If successful, this action returns a ticket resource with the updated custom fields in the response body.

Update CSAT data of a closed ticket

Updates a Customer Satisfaction Rating (CSAT) score and comment of a closed ticket.

HTTP request

PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/csat

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_id	int	Specifies the unique ID of a closed ticket.

Request body

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

Properties

Required	Type	Description
score	int	Specifies a CSAT score. Acceptable values range from 1 to 5, inclusive.

Optional	Type	Description
comment	string	Specifies a CSAT comment.

Request body example

{
    "score": 5,
    "comment": "Nori was super supportive!"
}

Response

If successful, this action returns a ticket resource with the updated CSAT score and comment.

Search tickets

Searches tickets in your Sendbird application.

HTTP request

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

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)
status2	string	Restricts the search scope to only retrieve tickets whose status matches the specified value. Acceptable values are limited to the following: - INITIALIZED: tickets whose conversation has been started with welcome messages, but when there is no reply from the corresponding customer. - PROACTIVE: tickets whose conversation has been started with proactive messages, but when there is no reply from the corresponding customer. - PENDING: tickets that haven't been assigned to any agent yet. - ACTIVE: tickets that are assigned to agents and under the interactions. - CLOSED: closed tickets whose interaction between the agent and customer is ended. - WORK_IN_PROGRESS: tickets that are yet to be closed for any number of reasons but which can be ACTIVE once the conversation between the agent and customer is started. - IDLE: tickets whose customer hasn't replied for a set amount of time after the agent's last response.
agent	string	Specifies the unique ID of an agent to restrict the search scope to only retrieve tickets assigned to a specific agent.
sendbird_id	string	Restricts the search scope to only retrieve tickets submitted by a customer with a specified Sendbird ID.
assignment_status	string	Restricts the search scope to only retrieve tickets whose assignment status matches the specified value. Acceptable values are limited to the following: - NOT_RESPONDED: tickets whose assignee hasn’t responded yet. - RESPONDED: tickets whose assignee responded. - IDLE: tickets whose assignee responded, but when there is no reply from the corresponding customer for a set amount of time. Once the customer replies, its assignment status will be changed to NOT_RESPONDED.
ticket_fields	object	Specifies the keys and values of ticket fields as a search filter. They should be URL encoded `JSON` objects.
channel_url	string	Restricts the search scope to only retrieve tickets related to a specified channel URL.
start_date	date	Specifies a starting date that restricts the search scope to retrieve tickets created between start_date and end_date, in YYYY-MM-DD format.
end_date	date	Specifies an ending date that restricts the search scope to retrieve tickets created between start_date and end_date, in YYYY-MM-DD format.
order	string	Specifies the method to sort a list of results. Acceptable values are limited to the following: - id (default): sorts by ticket ID in ascending order. - -id: sorts by ticket ID in descending order. - created_at: sorts by the time of ticket creation in ascending order. - -created_at: sorts by the time of ticket creation in descending order.

Response

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

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": "An internal error has occurred.",
    "code": 500500,
    "error": true
}

Error code	Error message	Description
deskp400105	start_date and end_date are required.	Either `start_date` or `end_date` is missing. Both parameters should be specified.
deskp400111	The value of limit should be smaller than 500.	The value specified in `limit` is invalid. Specify a value smaller than 500.
deskp400111	Invalid value for start_date or end_date.	The specified `start_date` or `end_date` is in incorrect format. Or, the value of `start_date` is later than that of `end_date`.
deskp400111	The specified sendbird_id doesn't exist.	The user with the specified `sendbird_id` doesn't exist.
deskp400111	The value of order should be id, -id, created_at, or -created_at.	The value specified in `order` is invalid. Acceptable values are `id`, `-id`, `created_at`, and `-created_at`.
deskp400111	ticket_fields should be in json format.	The specified `ticket_fields` is in incorrect format.
deskp400111	The specified ticket_fields doesn't exist.	The key specified in `ticket_fields` doesn't exist.
desk500500	An internal error has occurred.	An error occurred while processing the request.

Send a ticket closure confirmation

Sends a ticket closure confirmation to the customer.

HTTP request

POST https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/inquire_ticket_closure/

Parameters

The following table lists the parameters that this action supports.

Required

Parameter name	Type	Description
ticket_id	int	Specifies the unique ID of a ticket.

Response

if successful, this action returns a ticket resource in the response body.

Status: 200 OK

{
  "id": 210290,
  "project": 1061,
  "channelName": "Issue #506",
  "createdAt": "2024-01-23T01:51:38.699966Z",
  "channelUrl": "sendbird_group_channel_130488401_5076068588f7ae1e20cdb13e92e4b6b2db67bde1",
  "closedAt": null,
  "issuedAt": "2024-01-23T01:51:41.064214Z",
  "durationTime": null,
  "pendingTime": 706714,
  "conversationTime": null,
  "customer": {
    "id": 28383,
    "sendbirdId": "claire",
    "channelType": "SENDBIRD",
    "project": 1061,
    "createdAt": "2024-01-22T01:12:31.498240Z",
    "displayName": "claire",
    "photoThumbnailUrl": ""
  },
  "closeStatus": "NOT_CLOSED",
  "recentAssignment": {
    "id": 105932,
    "assignedTicket": 210290,
    "agent": {
      "id": 21473,
      "displayName": "ziggs kim",
      "project": 1061,
      "user": 1997,
      "sendbirdId": "sendbird_desk_agent_id_f54450c0-7eb7-44b8-9fd4-ce5d16e586ea",
      "role": "ADMIN",
      "createdAt": "2024-01-19T09:37:53.760475Z",
      "status": "ACTIVE",
      "connection": "OFFLINE",
      "email": "[email protected]",
      "photoThumbnailUrl": "",
      "connectionUpdatedAt": null,
      "tier": "INTERMEDIATE"
    },
    "assignedAt": "2024-01-31T06:10:15.498527Z",
    "responsedAt": null,
    "respondedAt": null,
    "endedAt": null,
    "status": "NOT_RESPONSED",
    "unreadCount": 1,
    "responseTime": null
  },
  "closeComment": null,
  "info": "{\"ticket\":{\"subject\":\"Issue #506\",\"requester\":{\"name\":\"claire\",\"email\":\"claire\"}}}",
  "messageCount": 1,
  "lastMessage": "The ticket is assigned to ziggs kim by ziggs kim.",
  "lastMessageSender": "PLATFORM",
  "lastMessageAt": "2024-01-31T06:10:15.877000Z",
  "lastUserMessageSender": "CUSTOMER",
  "lastUserMessageAt": "2024-01-23T01:51:40.794000Z",
  "lastMessageMembers": "[]",
  "updatedAt": "2024-01-31T06:10:15.962169Z",
  "lastMessagePayload": null,
  "firstAssignmentToCloseTime": null,
  "firstResponseTime": null,
  "channelType": "SENDBIRD_JAVASCRIPT",
  "data": "{}",
  "lastSeenAt": 0,
  "group": {
    "id": 1458,
    "name": "Default team",
    "key": null,
    "project": 1061,
    "createdAt": "2024-01-19T09:37:29.154744Z",
    "createdBy": null,
    "description": "Agents are added to this team as default. You can assign agents to other teams."
  },
  "customFields": [],
  "tags": [],
  "customerSatisfactionScore": null,
  "customerSatisfactionComment": null,
  "customerSatisfactionResponseAt": null,
  "customerSatisfactionSentAt": null,
  "priority": "MEDIUM",
  "priorityValue": 20,
  "status2": "ACTIVE",
  "relatedChannels": null,
  "lastAssignedAgent": 21473
}

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 RequestStatus: 401 Unauthorized

{
  "code": "deskp400201",
  "detail": "The specified Ticket ID doesn't exist"
}

On this page

Resource representation Actions List tickets View a ticket Create a ticket Update a ticket Update custom fields of a ticket Close a ticket Transfer a ticket to an agent Reopen a closed ticket Transfer tickets to a group Cancel assignment of a ticket Update CSAT data of a closed ticket Search tickets Send a ticket closure confirmation