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.
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.
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.
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}.
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. 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.
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.
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.
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.
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://.
{
"customFields": "{
\"request-type\":\"refund\", // Dropdown
\"region\": 3, // Integer
\"subject\":\"shoes\", // Text
\"order-list\":\"{\\\"url\\\":\\\"https://sendbird.com/orders\\\",\\\"text\\\":\\\"Track orders\\\"}\" // Link
}"
}
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.
{
"closeComment": "This issue has been resolved.",
"closeMessage": "This ticket is closed. If you have any other questions, please create a new ticket."
}
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.
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.
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.
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.
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 encodedJSON 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.