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.

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 simple flat JSON objects which have the following keys.

Name Type Comment
id integer Automatically assigned when created
title string The title of the trigger
active boolean Whether the trigger is active
position integer Position of the trigger, determines the order they will execute in
conditions Conditions An object that describes the conditions under which the trigger will execute
actions Actions An object describing what the trigger will do
description string The description of the trigger
created_at date The time the trigger was created
updated_at date The time of the last update of the trigger
Example
{
  "trigger": {
    "id": 25,
    "title": "Notify requester of comment update",
    "active": true,
    "actions": { ... },
    "conditions": { ... },
    "description": "Notifies requester that a comment was updated",
    "updated_at": "2012-09-25T22:50:26Z",
    "created_at": "2012-09-25T22:50:26Z"
  }
}

Conditions

Conditions check the value of ticket fields and select the ticket if the conditions are met. Conditions are represented as a JSON object with two arrays of one or more conditions.

Example

{
   "conditions": {
     "all": [
       { "field": "status", "operator": "less_than", "value": "solved" },
       { "field": "assignee_id", "operator": "is", "value": "296220096" }
     ],
     "any": [
     ]
   }
}

The first array lists all the conditions that must be met. The second array lists any condition that must be met.

Name Type Description
all array Logical AND. Tickets must fulfill all of the conditions to be considered matching
any array Logical OR. Tickets may satisfy any of the conditions to be considered matching

Each condition in an array has the following properties:

Name Type Description
field string The name of a ticket field
operator string A comparison operator
value string The value of a ticket field

Example

{ "field": "status", "operator": "less_than", "value": "solved" }

When specifying conditions in a PUT or POST request, use the "all" and "any" arrays without the "conditions" key. Example:

{
  "all": [
    { "field": "status", "operator": "less_than", "value": "solved" },
    { "field": "assignee_id", "operator": "is", "value": "296220096" }
  ],
  "any": [
    { "field": "current_tags", "operator": "includes", "value": "hello" }
  ],
  ...
}
Conditions reference

The following tables list the fields, allowed operators, and values of the conditions used in triggers, automations, views and SLA policies.

Common conditions

The following conditions are shared by triggers, automations, views and SLA policies.

field operator value
group_id is, is_not "" (no group assigned to the ticket) or the numeric ID of the group assigned to the ticket.
assignee_id is, is_not "" (nobody assigned to the ticket), current_user, all_agents, or the numeric ID of the agent assigned to the ticket.
requester_id is, is_not "" (no requester specified), current_user or the numeric ID of the requester or assignee.
organization_id is, is_not "" (no organization added to the ticket) or the numeric ID of the organization added to the ticket.
current_tags includes, not_includes A space-delimited list of tags to compare against the ticket's tags.
via_id is, is_not The numeric ID of the channel used to create the ticket. See the Via Types table.
recipient Omit the operator property For views and automations, the account name in the email address from which the ticket was received. For triggers and SLA policies, the full email address, which can include external addresses.

The following conditions are shared by triggers, automations, and views.

field operator value
type is, is_not question, incident, problem, or task
status is,
is_not,
less_than,
greater_than
new, open, pending, hold, solved, or closed
priority is,
is_not,
less_than,
greater_than
"" (no priority assigned to the ticket), low, normal, high, or urgent
description_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)
Single words or strings in the ticket subject. Not available in triggers.
locale_id is, is_not The numeric ID of the locale of the person who submitted the ticket. See List locales to list the available locale IDs for the account.
satisfaction_score is,
is_not,
less_than,
greater_than
good, bad, true (unoffered), or false (offered)

Triggers have the following additional operators for some shared fields.

Fields Additional trigger operators
status,
type,
priority,
group_id,
assignee_id,
requester_id,
organization_id,
satisfaction_ score
changed (omit value property),
value (changed to),
value_previous (changed from),
not_changed,
not_value (not changed to),
not_value_previous (not changed from)
Additional trigger conditions

Triggers have the following additional conditions.

field operator value
subject_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)
Single words or strings in the subject.
comment_includes_word includes (contains one word),
not_includes (contains none of the words),
is (contains string),
is_not (does not contain string)
Single words or strings in either the subject or body of the comment.
current_via_id is or is_not The numeric ID of the channel used to update the ticket. See the Via Types table.
update_type Omit the operator property. Create or Change
comment_is_public Omit the operator property. true, false, not_relevant (present), or requester_can_see_comment (present and requester can see comment)
ticket_is_public Omit the operator property. public, private, Available only if the arturo bit first_comment_private is enabled.
reopens less_than, greater_than, or is The number of times a ticket has moved from Solved to Open or Pending.
replies less_than, greater_than, or is The number of public agent comments.
agent_stations less_than, greater_than, or is The number of different agents to which a ticket has been assigned.
group_stations less_than, greater_than, or is The number of different groups to which a ticket has been assigned.
in_business_hours Omit the operator property. true or false. Available only if an administrator enabled business hours.
requester_twitter_followers_count less_than, greater_than, or is The number of the requester's Twitter followers.
requester_twitter_statuses_count less_than, greater_than, or is The total number of the requester's tweets.
requester_twitter_verified Omit the operator property Omit the value property. The condition is true if the requester has a verified Twitter account.
Additional SLA Policies conditions

SLA Policies have the following additional conditions.

field operator value
type_type_id is, is_not The numeric ID of the ticket type: 1 (question), 2 (incident), 3 (problem), or 4 (task)
current_via_id is or is_not The numeric ID of the channel used to update the ticket. See the Via Types table.
exact_created_at less_than, less_than_equal, greater_than or greater_than_equal The time the ticket was created.
Additional time-based conditions for automations and views

Automations and views have the following time-based conditions. Time-based conditions can only be used in all arrays, not in any arrays.

field value
NEW Hours since the ticket was created.
OPEN Hours since the ticket was opened.
PENDING Hours since the ticket was changed to pending.
SOLVED Hours since the ticket was changed to solved.
CLOSED Hours since the ticket was closed.
assigned_at Hours since assigned.
updated_at Hours since update.
requester_updated_at Hours since requester update.
assignee_updated_at Hours since assignee update.
due_date Hours since the due date. For tickets with the type set to Task.
until_due_date Hours until the due date. For tickets with the type set to Task.

The time-based conditions all share the same operator values:

operator
is
is_business_hours
less_than
less_than_business_hours
greater_than
greater_than_business_hours
Via Types
Via type Value
Web form 0
Email 4
Chat 29
Twitter 30
Twitter DM 26
Twitter like 23
Voicemail 33
Phone call (incoming) 34
Phone call (outbound) 35
CTI* voicemail 44
CTI phone call (inbound) 45
CTI phone call (outbound) 46
SMS 57
Get Satisfaction 16
Web Widget 48
Mobile SDK 49
Mobile 56
Help Center post 50
Web service (API) 5
Rule (trigger, automation) 8
Closed ticket 27
Ticket sharing 31
Facebook post 38
Facebook private message 41
Satisfaction prediction 54
Channel framework 55

*CTI - Computer Telephony Integration

Actions

Actions consist of an array of one or more actions.

Example

{
  "actions": [
    {"field": "status", "value": "open"},
    {"field": "assignee_id", "value": "296220096"}
  ]
}

Each action in the array has the following properties:

Name Type Description
field string The name of a ticket field to modify
value string The new value of the field

Example action

{ "field": "status", "value": "solved" }
Actions reference

Triggers, automations, and macros share the following actions.

field value
status Sets the ticket status. Takes new, open, pending, hold, solved, or closed, except for macros, which don't take new or closed.
type Sets the ticket type. Takes question, incident, problem, or task.
priority Sets the ticket priority. Takes low, normal, high, or urgent.
group_id Assigns the ticket to a group. Takes "" (unassign from a group if one has been assigned) or the numeric ID of a group.
assignee_id Assigns the ticket to a person. Takes "" (set to unassigned), current_user, or the numeric ID of an assignee or requester.
set_tags A space-delimited list of tags to insert in the ticket. The action replaces the current tags.
current_tags A space-delimited list of tags to add to existing tags.
remove_tags A space-delimited list of tags to remove from existing tags.
custom_fields_<id> Sets the value of a custom ticket field.
Additional actions for triggers and automations

In addition to the shared actions, triggers and automations share the following actions.

field value
satisfaction_score Sends a survey request to the ticket requester. Takes offered as a value.
notification_user Sends an email to a user. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: current_user, all_agent (all non-restricted agents), requester_id (the current requester), assignee_id (the current assignee), or the numeric ID of an agent.
notification_group Sends an email to a group. Takes an array of three strings specifying the email recipient, subject, and body. See "Notification emails" below. Possible recipient value: group_id (the currently assigned group), or the numeric ID of a group.
notification_target Sends a message to an external target. Takes an array of two strings specifying the numeric ID of the target and the message body.
tweet_requester Responds to the twitter requester with a tweet. Takes the text of the tweet.
cc CC's somebody on the ticket. Takes current_user or the numeric ID of an agent.
locale_id Sets the requester's language to one of your supported languages. Takes the numeric ID of a supported locale. See List locales to list the available locale IDs for the account.
requester.custom_fields.<field_key> Sets the value of a custom user field. The corresponding "value" property can be any string for a text field, or the id of an option for a dropdown field. An option id must be specified as a string. For a field's key or option id values, see Show User Field in User Fields
Additional actions for macros

In addition to the shared actions, macros have the following actions.

field value
subject Replaces the subject of a ticket. Takes the subject text.
comment_value Adds a comment to a ticket. Takes the comment text or an array of two strings specifying the comment channel and comment text. Possible comment channels : 'channel:all', 'channel:web' and 'channel:chat'
comment_value_html Adds a rich-text comment to a ticket.
comment_mode_is_public Makes a ticket comment public or private. Takes true (public) or false (private).
Notification emails

Notification emails are represented by an array of three strings specifying the email recipient, subject, and body.

Example

["293741756", "Leaking radiator", "Open the steam valve."]

The array is used for the value property of email notification actions. See "Additional actions for triggers and automations" above.

Example action

{
  "actions": [
    {"field": "notification_user", "value": ["293741756", "Leaking radiator", "Open the steam valve."]}
  ]
}

You can use dynamic content placeholders in the email subject and body. See Zendesk Support data object (placeholders) reference.

You can also use return (\r) and newline (\n) characters in the message body.

Example

["current_user","{{ticket.id}}: Leaking radiator","Open the steam valve.\r \nHope this helps."]

List Triggers

GET /api/v2/triggers.json

Lists all triggers for the current account

Allowed For:
  • Agents
Available Parameters

You can pass in any combination of the following optional filters:

Name Type Comment
active boolean Only active triggers if true, inactive triggers if false
sort_by string Possible values are alphabetical, created_at, updated_at, usage_1h, usage_24h, or usage_7d. Defaults to position
sort_order string One of asc or desc. Defaults to asc for alphabetical and position sort, desc for all others
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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers.json \
  -v -u {email}:{password}
Example Response
Status: 200 OK

{
  "triggers": [
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json",
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 8,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json",
      "id": 26,
      "title": "Assign priority tag",
      "raw_title": "{{dc.assign_priority_tag}}",
      "position": 9,
      "active": false,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Assign a ticket with a priority tag",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    }
  ],
  "previous_page": null,
  "next_page": null,
  "count": 2
}

Getting Triggers

GET /api/v2/triggers/{id}.json

Allowed For:
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/{id}.json \
  -v -u {email}:{password}
Example Response
Status: 200 OK

{
  "trigger": {
    "id": 25,
    "title": "Tickets updated <12 Hours",
    "raw_title": "{{dc.tickets_updated_last_12_hours}}"
    "position": 8,
    "active": true,
    "conditions": [ ... ],
    "actions": [ ... ],
    "description": "12 hours since the last ticket update",
    "updated_at": "2012-09-25T22:50:26Z",
    "created_at": "2012-09-25T22:50:26Z"
  }
}

The Via Type value is a number instead of a text string. See Via Types above for the keys.

List Active Triggers

GET /api/v2/triggers/active.json

Lists all active triggers

Allowed For:
  • Agents
Available Parameters

You can pass in any combination of the following optional filters:

Name Type Comment
sort_by string Possible values are alphabetical, created_at, updated_at, usage_1h, usage_24h, or usage_7d. Defaults to position
sort_order string One of asc or desc. Defaults to asc for alphabetical and position sort, desc for all others
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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/triggers/active.json \
  -v -u {email}:{password}
Example Response
Status: 200 OK

{
  "triggers": [
    {
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 8,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "id": 28,
      "title": "Close and redirect to topics",
      "raw_title": "{{dc.close_and_redirect}}",
      "position": 9,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and redirect a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    }
  ],
  "previous_page": null,
  "next_page": null,
  "count": 2
}

Create Trigger

POST /api/v2/triggers.json

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
Location: /api/v2/trigger/{new-trigger-id}.json

{
  "trigger": {
    "id":   9873843,
    "title": "Roger Wilco",
    ...
  }
}

Update Trigger

PUT /api/v2/triggers/{id}.json

Allowed For
  • Agents
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{id}.json \
  -H "Content-Type: application/json" -X PUT -d '{"trigger": {"title": "Roger Wilco II"}}'
Example Response
Status: 200 OK

{
  "trigger": {
    "id":   9873843,
    "title": "Roger Wilco II",
    ...
  }
}
Note

Updating a condition or action updates the containing array, clearing the other conditions or actions. Include all your conditions or actions when updating any condition or action.

Update Many Triggers

PUT /api/v2/triggers/update_many.json

Allowed For
  • Agents
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": 123, "position": 8}]}'
Example Response
Status: 200 OK

{
  "triggers": [
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/26.json",
      "id": 26,
      "title": "Assign priority tag",
      "raw_title": "{{dc.assign_priority_tag}}",
      "position": 8,
      "active": false,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Assign a ticket with a priority tag",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "url": "http://{subdomain}.zendesk.com/api/v2/triggers/25.json",
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 15,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    ...
  ]
}
Request Parameters

The PUT request takes one parameter, a triggers object that lists the triggers to update.

Each trigger must have the following parameters:

Name Description
id The ID of the trigger to update
position The new position of the trigger
Example Request
{
  "triggers": [
    {"id": 25, "position": 3},
    {"id": 23, "position": 5},
    {"id": 27, "position": 9},
    {"id": 22, "position": 7}
  ]
}

Delete Trigger

DELETE /api/v2/triggers/{id}.json

Allowed For
  • Agents
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/{id}.json \
  -H "Content-Type: application/json" -X DELETE
Example Response
Status: 200 OK

Bulk Delete Triggers

DELETE /api/v2/triggers/destroy_many.json

Deletes the triggers corresponding to the provided comma-separated list of IDs.

Allowed For
  • Agents
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
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"
}

Reorder Triggers

PUT /api/v2/triggers/reorder.json

Allowed For:
  • Agents
Using curl
curl -v -u {email}:{password} https://{subdomain}.zendesk.com/api/v2/triggers/reorder.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"trigger_ids": [6, 7, 18]}'
Example Response
Status: 200 OK

Search Triggers

GET /api/v2/triggers/search.json

Allowed For
  • Agents
Search Parameters

Required

Name Type Comment
query string Query string used to find all triggers with matching title

Optional

You can use any combination of the following optional parameters:

Name Type Comment
active boolean Only active triggers if true, inactive triggers if false
sort_by string Possible values are alphabetical, created_at, updated_at, and position. If unspecified, the triggers are sorted by relevance
sort_order string One of asc or desc. Defaults to asc for alphabetical and position sort, desc for all others
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
Using curl:
curl https://{subdomain}.zendesk.com/api/v2/triggers/search.json?query=close \
  -v -u {email}:{password}
Example Response
Status: 200 OK

{
  "triggers": [
    {
      "id": 25,
      "title": "Close and Save",
      "raw_title": "Close and Save",
      "position": 9,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "description": "Close and save a ticket",
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    },
    {
      "id": 28,
      "title": "Close and redirect to topics",
      "raw_title": "{{dc.close_and_redirect}}",
      "position": 9,
      "active": true,
      "conditions": [ ... ],
      "actions": [ ... ],
      "updated_at": "2012-09-25T22:50:26Z",
      "created_at": "2012-09-25T22:50:26Z"
    }
  ],
  "previous_page": null,
  "next_page": null,
  "count": 2
}