Triggers
A trigger consists of one or more actions performed when a ticket is created or updated. The actions are performed only if certain conditions are met. For example, a trigger can notify the customer when an agent changes the status of a ticket to Solved.
Triggers also may depend on one or more conditions being met.
For more information on conditions and actions, see the following Help Center articles:
All your triggers are checked from first to last each time a ticket is created or updated. The order of triggers is important because the actions of one trigger may affect another trigger. New triggers are added in last place by default.
For more information, see Streamlining workflow with ticket updates and triggers.
JSON Format
Triggers are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
actions | array | false | true | An array of actions describing what the trigger will do. See Actions reference |
active | boolean | false | false | Whether the trigger is active |
conditions | object | false | true | An object that describes the conditions under which the trigger will execute. See Conditions reference |
created_at | string | true | false | The time the trigger was created |
description | string | false | false | The description of the trigger |
id | integer | true | false | Automatically assigned when created |
position | integer | false | false | Position of the trigger, determines the order they will execute in |
raw_title | string | false | false | The raw format of the title of the trigger |
title | string | false | true | The title of the trigger |
updated_at | string | true | false | The time of the last update of the trigger |
url | string | true | false | The url of the trigger |
Example
{
"actions": [
{}
],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
}
List Triggers
GET /api/v2/triggers
Lists all triggers for the current account
Allowed For
- Agents
Sideloads
The following sideloads are supported. The usage sideloads are only supported on the Professional and Enterprise plans.
Name | Will sideload |
---|---|
app_installation | The app installation that requires each trigger, if present |
permissions | The permissions for each trigger |
usage_1h | The number of times each trigger has been used in the past hour |
usage_24h | The number of times each trigger has been used in the past day |
usage_7d | The number of times each trigger has been used in the past week |
usage_30d | The number of times each trigger has been used in the past thirty days |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
active | boolean | Query | false | Only active triggers if true , inactive triggers if false |
sort_by | string | Query | false | Possible values are alphabetical , created_at , updated_at , usage_1h , usage_24h , or usage_7d . Defaults to position |
sort_order | string | Query | false | One of asc or desc . Defaults to asc for alphabetical and position sort, desc for all others |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"triggers": [
{
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
},
{
"actions": [],
"active": false,
"conditions": {
"all": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
},
{
"field": "assignee_id",
"operator": "is",
"value": "296220096"
}
],
"any": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
}
]
},
"created_at": "2012-09-25T22:50:26Z",
"description": "Assign a ticket with a priority tag",
"id": 26,
"position": 9,
"raw_title": "{{dc.assign_priority_tag}}",
"title": "Assign priority tag",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json"
}
]
}
Create Trigger
POST /api/v2/triggers
Allowed For
- Agents
Using curl
curl -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers.json \
-H "Content-Type: application/json" -X POST -d \
'{"trigger": {"title": "Roger Wilco", "all": [{ "field": "status", \
"operator": "is", "value": "open" }, { "field": "priority", \
"operator": "less_than", "value": "high" }], \
"actions": [{ "field": "group_id", "value": "20455932" }]}}'
Example Response
Status 201 Created
{
"trigger": {
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
}
}
List Active Triggers
GET /api/v2/triggers/active
Lists all active triggers
Allowed For
- Agents
Sideloads
The following sideloads are supported:
Name | Will sideload |
---|---|
app_installation | The app installation that requires each trigger, if present |
permissions | The permissions for each trigger |
usage_1h | The number of times each trigger has been used in the past hour |
usage_24h | The number of times each trigger has been used in the past day |
usage_7d | The number of times each trigger has been used in the past week |
usage_30d | The number of times each trigger has been used in the past thirty days |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
sort_by | string | Query | false | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position" |
sort_order | string | Query | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/active.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"triggers": [
{
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
},
{
"actions": [],
"active": true,
"conditions": {
"all": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
},
{
"field": "assignee_id",
"operator": "is",
"value": "296220096"
}
],
"any": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
}
]
},
"created_at": "2012-09-25T22:50:26Z",
"description": "Assign a ticket with a priority tag",
"id": 26,
"position": 9,
"raw_title": "{{dc.assign_priority_tag}}",
"title": "Assign priority tag",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json"
}
]
}
List Trigger Action and Condition Definitions
GET /api/v2/triggers/definitions
Returns the definitions of the actions a trigger can perform and the definitions of the conditions under which a trigger can execute. The definition of the action includes a title ("Status"), a type ("list"), and possible values. The definition of the condition includes the same fields as well as the possible operators.
For a list of supported actions, see the Actions reference. For a list of supported conditions, see the Conditions reference
Allowed For
- Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/definitions.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"definitions": {
"actions": [
{
"group": "ticket",
"nullable": false,
"repeatable": false,
"subject": "status",
"title": "Status",
"type": "list",
"values": [
{
"enabled": true,
"title": "Open",
"value": "open"
},
{
"enabled": true,
"title": "Pending",
"value": "pending"
},
{
"enabled": true,
"title": "Solved",
"value": "solved"
},
{
"enabled": true,
"title": "Closed",
"value": "closed"
}
]
}
],
"conditions_all": [
{
"group": "ticket",
"nullable": false,
"operators": [
{
"terminal": false,
"title": "Is",
"value": "is"
},
{
"terminal": false,
"title": "Is not",
"value": "is_not"
},
{
"terminal": false,
"title": "Less than",
"value": "less_than"
},
{
"terminal": false,
"title": "Greater than",
"value": "greater_than"
},
{
"terminal": true,
"title": "Changed",
"value": "changed"
},
{
"terminal": false,
"title": "Changed to",
"value": "value"
},
{
"terminal": false,
"title": "Changed from",
"value": "value_previous"
},
{
"terminal": true,
"title": "Not changed",
"value": "not_changed"
},
{
"terminal": false,
"title": "Not changed to",
"value": "not_value"
},
{
"terminal": false,
"title": "Not changed from",
"value": "not_value_previous"
}
],
"repeatable": false,
"subject": "status",
"title": "Status",
"type": "list",
"values": [
{
"enabled": true,
"title": "New",
"value": "new"
},
{
"enabled": true,
"title": "Open",
"value": "open"
},
{
"enabled": true,
"title": "Pending",
"value": "pending"
},
{
"enabled": true,
"title": "Solved",
"value": "solved"
},
{
"enabled": true,
"title": "Closed",
"value": "closed"
}
]
}
],
"conditions_any": [
{
"group": "ticket",
"nullable": true,
"operators": [
{
"terminal": true,
"title": "Present",
"value": "present"
},
{
"terminal": true,
"title": "Not present",
"value": "not_present"
}
],
"repeatable": false,
"subject": "custom_fields_20513432",
"title": "Happy Gilmore",
"type": "list"
},
{
"group": "ticket",
"nullable": true,
"operators": [
{
"terminal": true,
"title": "Present",
"value": "present"
},
{
"terminal": true,
"title": "Not present",
"value": "not_present"
}
],
"repeatable": false,
"subject": "custom_fields_86492341",
"title": "total_time_field",
"type": "list"
}
]
}
}
Bulk Delete Triggers
DELETE /api/v2/triggers/destroy_many?ids={ids}
Deletes the triggers corresponding to the provided comma-separated list of IDs.
Allowed For
- Agents
Request Parameters
The DELETE request takes one parameter, an ids
object that lists the
triggers to delete.
Name | Description |
---|---|
ids | The IDs of the triggers to delete |
Example request
{
"ids": "25,23,27,22"
}
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
ids | string | Query | true | A comma separated list of trigger IDs |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/destroy_many.json?ids=1,2,3 \
-v -u {email}:{password} -X DELETE
Example Response
Status 204 No Content
Reorder Triggers
PUT /api/v2/triggers/reorder
Alters the firing order of triggers in the account. See
Reordering and sorting triggers
in the Zendesk Help Center. The firing order is set in a trigger_ids
array in the request body.
You must include every trigger id in your account to reorder the triggers. If not, the endpoint will return 404 Forbidden.
Allowed For
- Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/reorder.json \
-d '{"trigger_ids": [324376, 564937, 164318]}' \
-H "Content-Type: application/json" -X PUT \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"trigger": {
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
}
}
Search Triggers
GET /api/v2/triggers/search?query={query}
Allowed For
- Agents
Sideloads
The following sideloads are supported:
Name | Will sideload |
---|---|
app_installation | The app installation that requires each trigger, if present |
permissions | The permissions for each trigger |
usage_1h | The number of times each trigger has been used in the past hour |
usage_24h | The number of times each trigger has been used in the past day |
usage_7d | The number of times each trigger has been used in the past week |
usage_30d | The number of times each trigger has been used in the past thirty days |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
active | boolean | Query | false | Filter by only active triggers if true, inactive triggers if false |
query | string | Query | true | Query string used to find all triggers with matching title |
sort_by | string | Query | false | Possible values are "alphabetical", "created_at", "updated_at", "usage_1h", "usage_24h", or "usage_7d". Defaults to "position" |
sort_order | string | Query | false | One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/search.json?query=close \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"triggers": [
{
"actions": [],
"active": true,
"conditions": {
"all": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
},
{
"field": "assignee_id",
"operator": "is",
"value": "296220096"
}
],
"any": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
}
]
},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 9,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z"
},
{
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"id": 28,
"position": 9,
"raw_title": "{{dc.close_and_redirect}}",
"title": "Close and redirect to topics",
"updated_at": "2012-09-25T22:50:26Z"
}
]
}
Update Many Triggers
GET /api/v2/triggers/update_many
Updates the position or the active status of multiple triggers. Any additional properties are ignored.
Allowed For
- Agents
Request Parameters
The PUT request expects a triggers
object that lists the triggers to update.
Each trigger may have the following properties:
Name | Mandatory | Description |
---|---|---|
id | yes | The ID of the trigger to update |
position | no | The new position of the trigger |
active | no | The active status of the trigger (true or false) |
Example Request
{
"triggers": [
{"id": 25, "position": 3},
{"id": 23, "position": 5},
{"id": 27, "position": 9},
{"id": 22, "position": 7}
]
}
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/update_many.json \
-v -u {email}:{password} -H "Content-Type: application/json" \
-X PUT -d '{"triggers": [{"id": 26, "position": 8}, {"id": 25, "position": 15}]}'
Example Response
Status 200 OK
{
"count": 2,
"next_page": null,
"previous_page": null,
"triggers": [
{
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
},
{
"actions": [],
"active": false,
"conditions": {
"all": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
},
{
"field": "assignee_id",
"operator": "is",
"value": "296220096"
}
],
"any": [
{
"field": "status",
"operator": "less_than",
"value": "solved"
}
]
},
"created_at": "2012-09-25T22:50:26Z",
"description": "Assign a ticket with a priority tag",
"id": 26,
"position": 9,
"raw_title": "{{dc.assign_priority_tag}}",
"title": "Assign priority tag",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json"
}
]
}
Show Trigger
GET /api/v2/triggers/{trigger_id}
Allowed For
- Agents
The Via Type value is a number instead of a text string. See Via Types for the keys.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
trigger_id | integer | Path | true | The ID of the trigger |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"trigger": {
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
}
}
Update Trigger
PUT /api/v2/triggers/{trigger_id}
Allowed For
- Agents
Note
Updating a condition or action updates both the conditions and actions arrays, clearing all existing values of both arrays. Include all your conditions and actions when updating any condition or action.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
trigger_id | integer | Path | true | The ID of the trigger |
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}.json \
-H "Content-Type: application/json" -X PUT -d '{"trigger": {"title": "Roger Wilco II"}}'
Example Response
Status 200 OK
{
"trigger": {
"actions": [],
"active": true,
"conditions": {},
"created_at": "2012-09-25T22:50:26Z",
"description": "Close and save a ticket",
"id": 25,
"position": 8,
"raw_title": "Close and Save",
"title": "Close and Save",
"updated_at": "2012-09-25T22:50:26Z",
"url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json"
}
}
Delete Trigger
DELETE /api/v2/triggers/{trigger_id}
Allowed For
- Agents
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
trigger_id | integer | Path | true | The ID of the trigger |
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}.json \
-H "Content-Type: application/json" -X DELETE
Example Response
Status 204 No Content
List Trigger Revisions
GET /api/v2/triggers/{trigger_id}/revisions
List the revisions associated with a trigger.
Allowed For
- Agents
Sideloads
The following sideloads are supported:
Name | Will sideload |
---|---|
users | The user that authored each revision |
Pagination
This endpoint uses cursor-based pagination. The records are ordered in
descending order by the created_at
timestamp, then by id
on duplicate
created_at
values.
The cursor
parameter is a non-human-readable argument you can use to move
forward or backward in time.
Each JSON response will contain the following attributes to help you get more results:
after_url
requests more recent resultsbefore_url
requests older resultsafter_cursor
is the cursor to build the request yourselfbefore_cursor
is the cursor to build the request yourself
The properties are null if no more records are available.
You can request a maximum of 1000 records using the limit
parameter. If
no limit
parameter is supplied, it will default to 1,000.
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
trigger_id | integer | Path | true | The ID of the trigger |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions.json?limit=20 \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"after_cursor": "MTUwMTYwNzUyMi4wfHwxMzQ3NTMxNjcxfA==",
"after_url": "https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions.json?cursor=MTUwMTYwNzUyMi4wfHwxMzQ3NTMxNjcxfA%3D%3D\u0026limit=20",
"before_cursor": "fDE1MDE1NzUxMjIuMHx8MTM0NzM0MzAxMQ==",
"before_url": "https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions.json?cursor=fDE1MDE1NzUxMjIuMHx8MTM0NzM0MzAxMQ%3D%3D\u0026limit=20",
"count": 1,
"trigger_revisions": [
{
"author_id": 2,
"created_at": "2016-08-15T16:04:06Z",
"diff": {
"actions": [],
"active": [],
"conditions": {},
"description": [],
"source_id": 1,
"target_id": 2,
"title": []
},
"id": 100,
"snapshot": {
"actions": [
{
"field": "notification_target",
"value": [
"510312",
"{}"
]
}
],
"active": true,
"conditions": {
"all": [],
"any": [
{
"field": "current_tags",
"operator": "includes",
"value": "fire_bulk_1"
}
]
},
"description": "Notifies requester that a comment was updated",
"title": "Notify requester of comment update"
},
"url": "https://{subdomain}.zendesk.com/api/v2/trigger/123/revisions/100.json"
}
]
}
Show Trigger Revision
GET /api/v2/triggers/{trigger_id}/revisions/{trigger_revision_id}
Fetches a revision associated with a trigger.
Allowed For
- Agents
Sideloads
The following sideloads are supported:
Name | Will sideload |
---|---|
users | The user that authored each revision |
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
trigger_id | integer | Path | true | The ID of the trigger |
trigger_revision_id | integer | Path | false | The ID of the revision for a particular trigger |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/{trigger_id}/revisions/{trigger_revision_id}.json \
-v -u {email}:{password}
Example Response
Status 200 OK
{
"trigger_revision": {
"author_id": 3343,
"created_at": "2020-05-28T06:41:43Z",
"id": 1,
"snapshot": {
"actions": [
{
"field": "notification_target",
"value": [
"510312",
"{}"
]
}
],
"active": true,
"conditions": {
"all": [],
"any": [
{
"field": "current_tags",
"operator": "includes",
"value": "fire_bulk_1"
}
]
},
"description": null,
"title": "bulk_test_trigger_1"
},
"url": "https://example.zendesk.com/api/v2/triggers/261303831/revisions/1.json"
}
}