Apps Support API: Custom Ticket Statuses

What's changing?

As of mid-January 2023, Zendesk officially launched a new ability for admins to create custom ticket statuses for all agents to apply to a ticket.

There's some important disclaimers and behavioural changes related to this release and the Apps Support API that we want to let you know about.

Maintaining backwards compatibility with the ticket status property

Each ticket custom status will be assigned to a system status category when created.

The system status categories are the ticket statuses that exist today: new, open, pending, on hold, solved.

The ticket.status behaviour described below will ensure backwards compatibility with existing Zendesk Support apps to prevent a breaking change.

The ticket status property will return a system status category name

The list of valid values to be returned would include new, open, pending, on hold, solved, closed.

get

zafClient.get('ticket.status');

returns

> {
  "errors": {},
  "ticket.status": "open"
}

Setting the ticket status property will accept a system status category name

For a new ticket, the list of acceptable values will include: new, open, pending, hold and solved.

For an existing ticket, the list of acceptable values will include: open, pending, hold and solved.

set

zafClient.set('ticket.status', "pending");

returns

> {
  "errors": {},
  "ticket.status": "pending"
}

When ticket custom statuses is enabled on a Zendesk Support account and a Zendesk Support app sets the ticket status, this would trigger both the ticket.statusCategory.changed and ticket.customStatus.changed property change events.

This behaviour is expected because when a Zendesk Support app sets the ticket status, Zendesk Support assigns the default ticket custom status for that ticket status.

Get the list of system status categories and ticket custom statuses

The ticketFields:status Apps Support API has been retrofitted with the list of ticket custom statuses found in the submit button dropdown.

When ticket custom statuses is enabled on a Zendesk Support account, the ticket field option actions won't work on the ticket custom statuses that are found in the `options` and `optionValues` for the status ticket field.

The actions will continue to work as expected on the system statuses / system status categories.

Adding new properties to the Ticket object

We shall be adding two new properties to the Ticket object so that a Zendesk Support apps can get / set a ticket system status category and a ticket custom status using the Apps Support API.

Get the ticket status category

A Zendesk Support app will be able to retrieve the current ticket status category using:

get

zafClient.get('ticket.statusCategory');

The list of valid values to be returned would include new, open, pending, on hold, solved, closed.

returns

> {
  "errors": {},
  "ticket.statusCategory": "pending"
}

Set the ticket status category

For a new ticket, the list of acceptable values will include: new, open, pending, hold and solved.

For an existing ticket, the list of acceptable values will include: open, pending, hold and solved.

set

zafClient.set('ticket.statusCategory', "open");

returns

> {
  "errors": {},
  "ticket.statusCategory": "open"
}

When ticket custom statuses is enabled on a Zendesk Support account and a Zendesk Support app sets the ticket status, this would trigger both the ticket.statusCategory.changed and the ticket.customStatus.changed property change events.

This behaviour is expected because when a Zendesk Support app sets the ticket status, Zendesk Support assigns the default ticket custom status for that ticket status category.

Get the ticket custom status

A Zendesk Support app will be able to retrieve the current ticket custom status using:

get

zafClient.get('ticket.customStatus');

returns

> {
  "errors": {},
  "ticket.customStatus": {
   "id": number
   "name": "string // Name (agent view)
 }
}

Setting Custom Ticket Status using ticket.customStatus

A Zendesk Support app will also be able to set the ticket custom status using:

set

zafClient.set('ticket.customStatus', { id: 123456789 });

The value is expected to be a valid ticket custom status id. The setter would throw the below error when the ticket custom status id is not valid:

Could not find custom status with id 671172

A Zendesk Support app can fetch a list of ticket custom statuses for a Zendesk Support account using ticketFields:status from the Apps Support API and /api/v2/custom_statuses.json from the Zendesk Support API.

returns

> {
  "errors": {},
  "ticket.customStatus": {
   "id": number
   "name": string // Name (agent view)
 }
}

The ticket.statusCategory.changed and ticket.customStatus.changed property changed events are triggered when a Zendesk Support app sets a ticket custom status that belongs to a different system status category than the one that is assigned to the ticket.

A Zendesk Support app cannot set a ticket custom status for closed tickets.

Why is Zendesk doing this?

We're focused on ensuring any new features released into Zendesk Support are accessible to developers utilising the Apps Support API. Adding new properties to the ticket object (and refactoring old ones) will allow apps to get and set Custom Ticket Statuses without disrupting other apps using existing properties like ticket.category.

What do I need to do?

If you want to get or set a custom ticket status using the Apps Support API you will need to utilise the new endpoints specified above.