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.
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: |
closeStatus | string | The reason why the ticket has been closed. Valid values are: |
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. |
- API endpoints are relative to the base URL allocated to your application. In this page, the
/tickets
endpoint refers tohttps://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 |
---|---|
| |
| |
| |
| |
| |
|
Retrieves a list of all tickets in the application.
GET https://desk-api-{application_id}.sendbird.com/platform/v1/tickets
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) |
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: |
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: |
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
?limit=20&offset=40
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": "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. |
Retrieves information on a specific ticket.
GET https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}
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. |
If successful, this action returns a ticket resource in the response body.
Creates a new ticket.
POST https://desk-api-{application_id}.sendbird.com/platform/v1/tickets
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 |
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
{
"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"
}
If successful, this action returns a ticket resource in the response body.
Updates a ticket's priority and URLs of the related channels.
PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}
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. |
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
{
"priority": "LOW",
"relatedChannelUrls": "sendbird_group_channel_1,sendbird_group_channel_2"
}
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,
"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\"}]"
}
Closes a specific ticket.
PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/close
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. |
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
{
"closeComment": "This issue has been resolved."
}
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,
"channelType": "SENDBIRD",
"data": "{}",
"lastSeenAt": 0,
"group": {
"groupObject"
},
"customFields": [],
"customerSatisfactionScore": null,
"customerSatisfactionComment": null,
"priority": "MEDIUM",
"priorityValue": 20,
"status2": "CLOSED",
"relatedChannels": null
}
Updates custom fields of a specific ticket.
PATCH https://desk-api-{application_id}.sendbird.com/platform/v1/tickets/{ticket_id}/custom_fields
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. |
The following table lists the properties of an HTTP request that this action supports.
Properties
Required | Type | Description |
---|---|---|
customFields | JSON string | Specifies a |
Request body example
{
"customFields": "{\"phone_number\":\"0004-0005-0006\",\"delivery_address\":\"101, Hwangsaeul-ro 116beon-gil, Bundang-gu, Seongnam-si\"}"
}
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": "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
}