What's changing?
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
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.
zafClient.get('ticket.status');
> {
"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');
> {
"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");
> {
"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');
> {
"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:
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.
> {
"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.
7 comments
Vincent - SweetHawk
When referencing {{ticket.status}} in a webhook, currently we receive the name/label of the selected value in the user's locale rather than the internal system value (new/open/pending/etc). As part of this change we'd really like to see another placeholder which returns one of the system statuses, eg {{ticket.system_status}}.
0
Alan Byrne
When are these new ZAF APIs being activated. I have enabled custom statuses in my zendesk and can see these custom status values in the submit button, but when I call ZAF.get('ticket.customStats') or ZAF.get('ticket.statusCategory') I get an error back, see below
If I call ZAF.get('ticketFields:status'), I just get back details of the standard system statuses, there is nothing in the results to do with my custom status option values.
1
Rafael Santos
+1 to what Alan Byrne has flagged. I also get errors for the following calls:
I only get new/open/pending/hold/solved in the options.
Upon digging a bit on our instance's settings, I seem to have found the cause for this. These are all our custom_statuses related flags:
This would be caused by having custom_statuses_in_zaf disabled.
FYI Gaurav Parbat
0
JJ Miclat
Apologies all, the General Availability launch of Custom Ticket Statuses (and all of the associated Apps Support API updates) got delayed to mid-Jan 2023.
0
Alan Byrne
Any news on when the ZAF for custom statuses is going to be available?
0
Greg Katechis
Hi Alan! We were waiting on the GA release, which was delayed a bit. Now that it has been/is in the process of being GA'd, it should be going into rollout soon, I'm just not 100% sure exactly when that will be for each customer. I've reached out to the team responsible for deploying and monitoring the rollout and when I hear back, I'll drop you a line with a more accurate timeline!
0
JJ Miclat
Hi all,
Custom ticket statuses is officially GA'd at 100% rollout across all Zendesk customers on Agent Workspace.
Cheers,
JJ
0