Home

Desk

Platform API

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

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 first sent a message, in ISO 8601 format.
durationTime	int	The time in seconds taken from when the customer first sends a message until the ticket is closed.
pendingTime	int	The time in seconds taken from when the customer first sends a message until the ticket is assigned to an agent.
conversationTime	int	The time in seconds taken from when the customer first sends a message until the last message is sent regardless of who sent it.
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 in the Dashboard. Valid values are: - 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: - 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. - NOT_CONFIRMED (deprecated): indicates the agent asked a customer to close the ticket, but the customer hasn't confirmed yet. - CONFIRMED (deprecated): indicates the customer confirmed to close the ticket when requested by an agent. If the Close ticket after customer's confirm option is turned on, the ticket will be closed automatically once a customer confirms the request.
recentAssignment	nested object	The detailed information about the last assignment.
closeComment	string	The comment left when the ticket was closed.
info	string	The information of when the ticket was created.
messageCount	int	The total count of messages in the ticket.
lastMessage	string	The last message in the ticket.
lastMessageSender	string	The sender of the last message. Valid values are CUSTOMER, AGENT, and PLATFORM.
lastMessageAt	datetime	The date and time when the last message was sent, in ISO 8601 format.
lastUserMessageSender	string	The sender of the last text message except the admin messages from Desk Platform. Valid values are CUSTOMER and AGENT.
lastUserMessageAt	datetime	The date and time when the customer sent the last message, in ISO 8601 format.
updatedAt	datetime	The date and time when the ticket information was last updated, in ISO 8601 format.
firstAssignmentToCloseTime	int	The time in seconds recorded from the agent's first response until the ticket is closed.
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 this ticket.
priority	string	The priority of the ticket. Valid values are URGENT, HIGH, MEDIUM, and LOW.
priorityValue	int	The priority value of the ticket. Higher values stand for higher priority. Valid values are 10, 20, 30, and 40, which can be set in increments of 10.
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}.

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.
Close a ticket	`PATCH` /tickets/{ticket_id}/close Closes a ticket.
Update custom fields of a ticket	`PATCH` /tickets/{ticket_id}/custom_fields Updates custom fields of a specific ticket.

List tickets

Retrieves a list of all tickets in the application.

HTTP request

Light Color Skin

Copy

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

Parameters

The following table lists the parameters that this action supports.

Parameters

Optional	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 before retrieving the next page in the result set. This is used to adjust the starting index of the next page. (Default: 0)
status2	string	Restricts the search scope to only retrieve tickets whose status matches the specified value. Acceptable values are: - 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	Restricts the search scope to only retrieve tickets assigned to a specific agent.
assignment_status	string	Restricts the search scope to only retrieve tickets whose assignment status matches the specified value. Acceptable values are: - NOT_RESPONSED: tickets whose assignee hasn’t responded yet. - RESPONSED: 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_RESPONSED.
channel_url	string	Restricts the search scope to only retrieve tickets related to a specified channel URL.
q	string	Restricts the search scope to only retrieve tickets that match with the specified channel name, display name or Sendbird ID of the customer.
start_date	datetime	Specifies a starting date and time that restricts the search scope to retrieve tickets created 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 created between start_date and end_date, in ISO 8601 format.
order	string	Specifies a property to sort a list of results in ascending order. Any properties in the result set can be set as a value, including id, channel_name, closed_at, and created_at can be used. If you want to sort the results in descending order, add minus in front of the value, for example, set as -id instead of id. (Default: id)

Query string example

Light Color Skin

Copy

?limit=20&offset=40

Response

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

Status: 200 OK

Light Color Skin

Copy

{
    "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": "mike.angel@sendbird.com",
                    "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",
                "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,
            "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 assinged to this time."
            },
            "customFields": [],
            "customerSatisfactionScore": null,
            "customerSatisfactionComment": null,
            "priority": "URGENT",
            "priorityValue": 40,
            "status2": "CLOSED",
            "relatedChannels": null
        },
        ... # More tickets
    ]
}

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

Light Color Skin

Copy

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

Parameters

The following table lists the parameters that this action supports.

Parameters

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

Response

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

Create a ticket

Creates a new ticket.

HTTP request

Light Color Skin

Copy

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 to create, which will be the group channel name in Sendbird Chat platform as well.
customerId	int	Sepcifies 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 a key to assign the ticket to a specific group. The created ticket is assigned to the group that matches with this key, otherwise the ticket is assigned to the Default team if the groupKey isn’t specified.
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 a priority of the ticket. Acceptable values are URGENT, HIGH, MEDIUM, and LOW. (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

Light Color Skin

Copy

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

Light Color Skin

Copy

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

Parameters

The following table lists the parameters that this action supports.

Parameters

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

Request body

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

Properties

Optional	Type	Description
priority	string	Specifies the priority of a ticket. Valid values are URGENT, HIGH, MEDIUM, and LOW. (Default: MEDIUM)
relatedChannelUrls	string	Specifies the URLs of the group channels in Sendbird Chat platform that are related to this 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 3 group channel URLs can be added per ticket.

Request body example

Light Color Skin

Copy

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

Light Color Skin

Copy

{
    "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,
    "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, Hwangsaeul-ro 116beon-gil, Bundang-gu, Seongnam-si"
        }
    ],
    "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\"}]"
}

Close a ticket

Closes a specific ticket.

HTTP request

Light Color Skin

Copy

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.

Parameters

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

Request body

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

Properties

Optional	Type	Description
closeComment	string	Specifies the notes for ticket close.

Request body example

Light Color Skin

Copy

{
    "closeComment": "This issue has been resolved."
}

Response

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

Status: 200 OK

Light Color Skin

Copy

{
    "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,
    "channelType": "SENDBIRD",
    "data": "{}",
    "lastSeenAt": 0,
    "group": {
        "groupObject"
    },
    "customFields": [],
    "customerSatisfactionScore": null,
    "customerSatisfactionComment": null,
    "priority": "MEDIUM",
    "priorityValue": 20,
    "status2": "CLOSED",
    "relatedChannels": null
}

Update custom fields of a ticket

Updates custom fields of a specific ticket.

HTTP request

Light Color Skin

Copy

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 the target 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 key must not have a comma (,) and its length is limited to 128 characters. The value must be a string and its length is limited to 128 characters. This property can have up to 10 custom items. New key-value items in the property are added when there are no items with the keys. The existing fields are updated with new values when there are already items with the keys.

Request body example

Light Color Skin

Copy

{
    "customFields": "{\"phone_number\":\"0004-0005-0006\",\"delivery_address\":\"101, Hwangsaeul-ro 116beon-gil, Bundang-gu, Seongnam-si\"}"
}

Response

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

Status: 200 OK

Light Color Skin

Copy

{
    "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": "summer_winter",
        "channelType": "SENDBIRD",
        "project": 13,
        "createdAt": "2019-03-12T05:45:33.808794Z",
        "memo": null,
        "displayName": "summer_is_happy",
        "photoThumbnailUrl": "https://sendbird.com/main/img/profiles/profile_smile_summer.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,
    "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": "phone_number",
            "value": "0004-0005-0006"
        },
        {
            "id": 241,
            "key": "delivery_address",
            "value": "101, Hwangsaeul-ro 116beon-gil, Bundang-gu, Seongnam-si"
        }
    ],
    "customerSatisfactionScore": null,
    "customerSatisfactionComment": null,
    "priority": "MEDIUM",
    "priorityValue": 20,
    "status2": "INITIALIZED",
    "relatedChannels": null
}

Customer

Ticket

Chat messages

ON THIS PAGE

List tickets View a ticket Create a ticket Update a ticket Close a ticket Update custom fields of a ticket