Chat triggers reference for developers

<h2 id="h_01K1XKWJGW2SS17F8NXW6F56QS">JSON format</h2><p dir="auto">Triggers are represented as JSON objects with the following attributes.</p><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td style="text-align: center;"><strong>Name</strong></td>
<td><strong> Type</strong></td>
<td><strong>Read-only</strong></td>
<td><strong> Description</strong></td>
</tr>
<tr>
<td>name</td>
<td>string</td>
<td>No</td>
<td>The name of the trigger</td>
</tr>
<tr>
<td>enabled</td>
<td>integer</td>
<td>No</td>
<td>Whether the trigger is enabled or not</td>
</tr>
<tr>
<td>description</td>
<td>string</td>
<td>No</td>
<td>The description of the trigger</td>
</tr>
<tr>
<td>definition</td>
<td>object</td>
<td>no</td>
<td>The definition of the trigger. For details, see <strong>Trigger definitions </strong>below.</td>
</tr>
</tbody></table></figure><h2 id="h_01K1XKWJGW9ECECYZPF3JF2F0E">Trigger definitions</h2><p dir="auto">Note: Definitions are not editable in Update Trigger. </p><p dir="auto">For detailed descriptions of each trigger, see <a href="https://support.zendesk.com/hc/en-us/articles/4408842880282-Zendesk-Chat-triggers-conditions-and-actions-reference" target="_blank" rel="noopener noreferrer">Trigger conditions and action reference</a>.</p><p dir="auto">Triggers are simply defined using JSON. Each trigger is a JSON object with 3 keys:</p><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Trigger Definition Keys</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>event</td>
<td>(JSON String) Type of event that this trigger gets activated for. For a list of events, see Trigger events.</td>
</tr>
<tr>
<td>condition</td>
<td>(JSON List) Condition that must be fulfilled for this trigger to perform its actions. For more details, see Condition types</td>
</tr>
<tr>
<td>action</td>
<td>action (JSON List) List of actions to be performed when the condition is fulfilled. For more details, see Trigger Actions.</td>
</tr>
</tbody></table></figure><h2 id="h_01K1XKWJGWZNNX888KHC9JQH41">Trigger events</h2><p dir="auto">You can use the following events:</p><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Trigger event</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>page_enter</td>
<td>This event is triggered when a visitor has loaded the chat widget.</td>
</tr>
<tr>
<td>chat_requested</td>
<td>This event is triggered when a visitor requests a chat.</td>
</tr>
<tr>
<td>chat_message</td>
<td>This event is triggered when a visitor sends a chat message.</td>
</tr>
</tbody></table></figure><h2 id="h_01K1XKWJGWTW5P9QJTZ6SJFDZB">Condition events</h2><p dir="auto">You can use the following conditions:</p><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Condition type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>or</td>
<td>Check any of the conditions are fulfilled</td>
</tr>
<tr>
<td>and</td>
<td>Check all of the conditions are fulfilled</td>
</tr>
</tbody></table></figure><h2 id="h_01K1XKWJGWMR9PQ20S3MK6KPKP">Condition variable operators</h2><p dir="auto">You can use the following operators for your condition variables. Operators may not be available for different variables.</p><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Operator</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>eq</td>
<td>Equals</td>
</tr>
<tr>
<td>neq</td>
<td>Not equal</td>
</tr>
<tr>
<td>lt</td>
<td>Less than</td>
</tr>
<tr>
<td>gt</td>
<td>Greater than</td>
</tr>
<tr>
<td>lte</td>
<td>Less than or equal to</td>
</tr>
<tr>
<td>gte</td>
<td>Greater than or equal to</td>
</tr>
<tr>
<td>icontains</td>
<td>Contains</td>
</tr>
<tr>
<td>nicontains</td>
<td>Does not contain</td>
</tr>
<tr>
<td>contains</td>
<td>Contains (case sensitive)</td>
</tr>
<tr>
<td>ncontains</td>
<td>Does not contain (case sensitive)</td>
</tr>
<tr>
<td>regex</td>
<td>Regular expression matches (case sensitive)</td>
</tr>
<tr>
<td>iregex</td>
<td>Regular expression</td>
</tr>
</tbody></table></figure><h2 id="h_01K1XKWJGX06K9221XWE98XMKJ">Condition variables</h2><p dir="auto">You can use the following variables:</p><h3 id="h_01K1XKWJGXSDPN797G8909A27C">Time and date variables </h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@hour_of_day</td>
<td>Hour of day (UTC timezone), 0 to 23</td>
</tr>
<tr>
<td>@day_of_week</td>
<td>Day of the week. 0 = Monday, 6 = Sunday</td>
</tr>
<tr>
<td>@visitor_time_on_page</td>
<td>Number of seconds visitor has stayed on current page</td>
</tr>
<tr>
<td>@visitor_time_on_site</td>
<td>Number of seconds visitor has stayed on your site</td>
</tr>
<tr>
<td>stillOnSite</td>
<td>Delay (in secs) before checking next condition</td>
</tr>
<tr>
<td>stillOnPage</td>
<td>Delay (in secs) before checking next condition</td>
</tr>
</tbody></table></figure><h3 id="h_01K1XKWJGXCC6QQWK9GC7A3ZB5">Visitor location</h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@visitor_ip</td>
<td>IP address of the visitor (xxx.xxx.xxx.xxx)</td>
</tr>
<tr>
<td>@visitor_hostname</td>
<td>Host name of visitor's IP address</td>
</tr>
<tr>
<td>@visitor_city</td>
<td>City the visitor is from</td>
</tr>
<tr>
<td>@visitor_region</td>
<td>Region the visitor is from</td>
</tr>
<tr>
<td>@visitor_country_code</td>
<td>Two-letter country code of visitor</td>
</tr>
<tr>
<td>@visitor_country_name</td>
<td>Country the visitor is from</td>
</tr>
</tbody></table></figure><h3 id="h_01K1XKWJGXQJYD3NRMW02NFF1T">Previous visit information</h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@visitor_previous_visits</td>
<td>Number of times visitor previously visited. New visits = 0</td>
</tr>
<tr>
<td>@visitor_previous_chats</td>
<td>Number of times visitor chatted with agents. New chats = 0</td>
</tr>
</tbody></table></figure><h3 id="h_01K1XKWJGXMTDWFFWS3FWAEHBV">Page information</h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@visitor_page_url</td>
<td>URL of the page the visitor is currently on</td>
</tr>
<tr>
<td>@visitor_page_title</td>
<td>Title of the page the visitor is currently on</td>
</tr>
<tr>
<td>@visitor_page_count</td>
<td>Number of pages visitor has viewed. First page = 1</td>
</tr>
<tr>
<td>@referrer</td>
<td>URL of the previous page visitor was on</td>
</tr>
</tbody></table></figure><h3 id="h_01K1XKWJGXPH35600Y4FJAAX76">Visitor information</h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@visitor_name</td>
<td>Name of the visitor</td>
</tr>
<tr>
<td>@visitor_email</td>
<td>Email of the visitor</td>
</tr>
<tr>
<td>@visitor_referrer</td>
<td>Referrer URL of the visitor (when they entered your site)</td>
</tr>
<tr>
<td>@visitor_search_engine</td>
<td>Referring search engine, if applicable</td>
</tr>
<tr>
<td>@visitor_search_terms</td>
<td>Referring search term, if applicable</td>
</tr>
<tr>
<td>@visitor_tags</td>
<td>Name of tag (set by the action Set Tag)</td>
</tr>
<tr>
<td>@visitor_triggered</td>
<td>'true' if visitor has been triggered (set by the action Set Triggered)</td>
</tr>
<tr>
<td>@visitor_department_id</td>
<td> Visitor's department (set by the action Set Visitor Department or by Javascript API)</td>
</tr>
</tbody></table></figure><h3 id="h_01K1XKWJGXYMPR9VQ8SV4NM5QR">Visitor software/computer</h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@visitor_user_agent</td>
<td>Visitor's browser user-agent string</td>
</tr>
<tr>
<td>@visitor_browser</td>
<td>Visitor's browser</td>
</tr>
<tr>
<td>@visitor_platform</td>
<td>Visitor's operating system/platform</td>
</tr>
</tbody></table></figure><h3 id="h_01K1XKWJGXK59HHAYFMG7RPT97">Online statuses</h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@account_status</td>
<td>Status of your account (online/away/offline)</td>
</tr>
<tr>
<td>@visitor_status</td>
<td>Status of the visitor (online/idle/offline)</td>
</tr>
</tbody></table></figure><h3 id="h_01K1XKWJGX0Q9155PP0C73ZW27">Chat-related information</h3><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Type</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>@visitor_requesting_chat</td>
<td>'true' if visitor is requesting chat</td>
</tr>
<tr>
<td>@visitor_served</td>
<td>'true' if visitor is currently served by agents</td>
</tr>
<tr>
<td>@department</td>
<td>Department (name) that visitor chooses on the chat request form</td>
</tr>
<tr>
<td>@visitor_served</td>
<td>'true' if visitor is currently served by agents</td>
</tr>
<tr>
<td>@sender</td>
<td>Name of the sender of the message</td>
</tr>
<tr>
<td>@sender_type</td>
<td>Either 'agent' or 'visitor'</td>
</tr>
<tr>
<td>@message</td>
<td>The message being sent</td>
</tr>
</tbody></table></figure><p dir="auto"> </p><h2 id="h_01K1XKWJGXWQ0520ZXQ24EBV2N">Trigger actions</h2><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody>
<tr>
<td><strong>Action</strong></td>
<td><strong>Parameters</strong></td>
<td><strong>Description</strong></td>
</tr>
<tr>
<td>sendMessageToVisitor</td>
<td>Name of agent and message (string)</td>
<td>Sends a message to visitor</td>
</tr>
<tr>
<td>setTriggered</td>
<td>True/false (boolean)</td>
<td>Sets the "triggered" flag of the visitor</td>
</tr>
<tr>
<td>wait</td>
<td>Duration (in secs) (number)</td>
<td>Waits for specified number of seconds, then performs the next action in the list if the visitor is still online</td>
</tr>
<tr>
<td>addTag</td>
<td>Tag Name (string)</td>
<td>Adds a tag to the visitor, which is visible on the dashboard Visitor List</td>
</tr>
<tr>
<td>removeTag</td>
<td>Tag Name (string)</td>
<td>Removes a tag from the visitor's session</td>
</tr>
<tr>
<td>banVisitor</td>
<td>Reason (string)</td>
<td>Ban visitor with reason</td>
</tr>
<tr>
<td>banIp</td>
<td>Reason (string)</td>
<td>Ban visitor's IP address with reason</td>
</tr>
<tr>
<td>setName</td>
<td>Name of Visitor (string)</td>
<td>Sets the name of the visitor</td>
</tr>
<tr>
<td>setDepartment</td>
<td>Department ID (number)</td>
<td>Set's the visitor's current department</td>
</tr>
<tr>
<td>setNote</td>
<td>Note (string) </td>
<td>Sets a note for the visitor, which is visible in the dashboard and is persistent</td>
</tr>
<tr>
<td>appendNote</td>
<td> Note (string)</td>
<td> Appends note to end of visitor's current note</td>
</tr>
</tbody></table></figure><h2 id="h_01K1XKWJGXM9KBVJZ0C0D1Q29R">Get all triggers</h2><p dir="auto">GET /api/v2/triggers</p><p dir="auto">Lists all the triggers of an account.<br>Allowed for</p><pre class="wysiwyg-code-block"><code class="language-auto">Owner
Administrator
</code></pre><p dir="auto">Using cURL</p><p dir="auto">curl href="https://www.zopim.com/api/v2/triggers"https://www.zopim.com/api/v2/triggers \<br>-v -u {email_address}:{password}</p><p dir="auto">Example Response</p><p dir="auto">HTTP/1.1 200 OK<br>Content-Type: application/json</p><p dir="auto">[<br>{<br>"name" : "Good Trigger",<br>"enabled" : 1,<br>"description" : "Visitor entered page"<br>},<br>{<br>"name" : "Better Trigger",<br>"enabled" : 1,<br>"description" : "Visitor requested chat"<br>}<br>]</p><p dir="auto">Get a Trigger</p><p dir="auto">GET /api/v2/triggers/{trigger_name}</p><p dir="auto">Allows an account owner/administrator to retrieve a trigger by name.<br>Allowed for</p><pre class="wysiwyg-code-block"><code class="language-auto">Owner
Administrator
</code></pre><p dir="auto">Using cURL</p><p dir="auto">curl href="https://www.zopim.com/api/v2/triggers/%7Btrigger_name%7D"https://www.zopim.com/api/v2/triggers/{trigger_name} \<br>-v -u {email_address}:{password}</p><p dir="auto">Example Response</p><p dir="auto">HTTP/1.1 200 OK<br>Content-Type: application/json</p><p dir="auto">{<br>"name" : "Good Trigger",<br>"enabled" : 1,<br>"description" : "Visitor requested chat",<br>}</p><p dir="auto">Create Trigger</p><p dir="auto">POST /api/v2/triggers</p><p dir="auto">Allows an account owner/administrator to add a trigger to an account.<br>Allowed for</p><pre class="wysiwyg-code-block"><code class="language-auto">Owner
Administrator
</code></pre><p dir="auto">Using cURL</p><p dir="auto">curl href="https://www.zopim.com/api/v2/triggers"https://www.zopim.com/api/v2/triggers \<br>-d '{<br>"name" : "Good Trigger",<br>"enabled" : 1,<br>"description" : "Visitor requested chat"<br>}' \<br>-v -u {email_address}:{password} \<br>-X POST -H "Content-Type: application/json"</p><p dir="auto">Example Response</p><p dir="auto">HTTP/1.1 201 Created<br>Content-Type: application/json</p><p dir="auto">{<br>"name" : "Good Trigger",<br>"enabled" : 1,<br>"description" : "Visitor requested chat",<br>}</p><!--<p dir="auto">Example Trigger Definition using cURL<br />Proactive Chat</p>
<p dir="auto">Automatically send a message of our choice to a visitor who's been browsing through your website for 20 seconds</p>
<p dir="auto">curl <a href="https://www.zopim.com/api/v2/triggers">https://www.zopim.com/api/v2/triggers</a> \<br />-d '{<br />"name" : "Proactive Chat",<br />"enabled" : 1,<br />"description" : "Proactive Chat for Visitors",<br />"definition" : {<br />"event" : "page_enter",<br />"condition" : [<br />"and",<br />[<br />"eq",<br />"@visitor_requesting_chat",<br />false<br />],<br />[<br />"eq",<br />"@visitor_served",<br />false<br />],<br />[<br />"stillOnSite",<br />20<br />]<br />],<br />"actions" : [<br />[<br />"sendMessageToVisitor",<br />"Zopim Agent",<br />"Hi there, welcome to our website"<br />],<br />[<br />"setTriggered",<br />true<br />]<br />]<br />}<br />}' \<br />-v -u {email_address}:{password} \<br />-X POST -H "Content-Type: application/json"</p>--><p dir="auto">Targeting messages to a specific page/directory</p><p dir="auto">Sends an automated message to a specific URL or a directory</p><p dir="auto">curl href="https://www.zopim.com/api/v2/triggers"https://www.zopim.com/api/v2/triggers \<br>-d '{<br>"name" : "Stripe Shoe",<br>"enabled" : 1,<br>"description" : "Send discount code for Stripe Shoe",<br>"definition" : {<br>"event" : "page_enter",<br>"condition" : [<br>"and",<br>[<br>"icontains",<br>"@visitor_page_url",<br>"stripshoe"<br>],<br>[<br>"stillOnPage",<br>20<br>]<br>],<br>"actions" : [<br>[<br>"sendMessageToVisitor",<br>"Timmy",<br>"We have a discount code for you! Use DISCOUNT10 on your next checkout"<br>]<br>]<br>}<br>}' \<br>-v -u {email_address}:{password} \<br>-X POST -H "Content-Type: application/json"</p><p dir="auto">For detailed configuration of Triggers, go to account's Trigger page<br>Update Trigger</p><p dir="auto">PUT /api/v2/triggers/{trigger_name}</p><p dir="auto">Allows an account owner/administrator to update the data of a trigger.<br>Allowed for</p><pre class="wysiwyg-code-block"><code class="language-auto">Owner
Administrator
</code></pre><p dir="auto">Using cURL</p><p dir="auto">curl href="https://www.zopim.com/api/v2/triggers/%7Btrigger_name%7D"https://www.zopim.com/api/v2/triggers/{trigger_name} \<br>-d '{<br>"name" : "Best Trigger",<br>"description" : "Visitor requested new chat"<br>}' \<br>-v -u {email_address}:{password} \<br>-X PUT -H "Content-Type: application/json"</p><p dir="auto">Example Response</p><p dir="auto">HTTP/1.1 200 OK<br>Content-Type: application/json</p><p dir="auto">{<br>"name" : "Best Trigger",<br>"enabled" : 1,<br>"description" : "Visitor requested new chat",<br>}</p><p dir="auto">Delete Trigger</p><p dir="auto">DELETE /api/v2/triggers/{trigger_name}</p><p dir="auto">Allows an account owner/administrator to delete a trigger.<br>Allowed for</p><pre class="wysiwyg-code-block"><code class="language-auto">Owner
Administrator
</code></pre><p dir="auto">Using cURL</p><p dir="auto">curl href="https://www.zopim.com/api/v2/triggers/%7Btrigger_name%7D"https://www.zopim.com/api/v2/triggers/{trigger_name} \<br>-v -u {email_address}:{password} -X DELETE</p><p dir="auto">Example Response</p><p dir="auto">HTTP/1.1 204 OK<br>Content-Type: application/json</p><script id="docs-schema-markup" type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408886111130",
"url": "https://support.zendesk.com/hc/en-us/articles/4408886111130-Chat-triggers-reference-for-developers",
"headline": "Chat triggers reference for developers",
"description": "You can create, retrieve, update, and delete chat triggers using a JSON-based API that defines trigger events, conditions, and actions to automate visitor interactions on your site.",
"articleSection": "Setting up live chat",
"datePublished": "2021-10-16T16:04:37+00:00",
"dateModified": "2025-08-05T17:19:24+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408886111130"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
}
}
</script>