Chat triggers reference for developers

JSON format Triggers are represented as JSON objects with the following attributes.

Name
Type
Read-only
Description


name
string
No
The name of the trigger


enabled
integer
No
Whether the trigger is enabled or not


description
string
No
The description of the trigger


definition
object
no
The definition of the trigger. For details, see Trigger definitions below.

Trigger definitions Note: Definitions are not editable in Update Trigger. For detailed descriptions of each trigger, see Trigger conditions and action reference. Triggers are simply defined using JSON. Each trigger is a JSON object with 3 keys:

Trigger Definition Keys
Description


event
(JSON String) Type of event that this trigger gets activated for. For a list of events, see Trigger events.


condition
(JSON List) Condition that must be fulfilled for this trigger to perform its actions. For more details, see Condition types


action
action (JSON List) List of actions to be performed when the condition is fulfilled. For more details, see Trigger Actions.

Trigger events You can use the following events:

Trigger event
Description


page_enter
This event is triggered when a visitor has loaded the chat widget.


chat_requested
This event is triggered when a visitor requests a chat.


chat_message
This event is triggered when a visitor sends a chat message.

Condition events You can use the following conditions:

Condition type
Description


or
Check any of the conditions are fulfilled


and
Check all of the conditions are fulfilled

Condition variable operators You can use the following operators for your condition variables. Operators may not be available for different variables.

Operator
Description


eq
Equals


neq
Not equal


lt
Less than


gt
Greater than


lte
Less than or equal to


gte
Greater than or equal to


icontains
Contains


nicontains
Does not contain


contains
Contains (case sensitive)


ncontains
Does not contain (case sensitive)


regex
Regular expression matches (case sensitive)


iregex
Regular expression

Condition variables You can use the following variables: Time and date variables

Type
Description


@hour_of_day
Hour of day (UTC timezone), 0 to 23


@day_of_week
Day of the week. 0 = Monday, 6 = Sunday


@visitor_time_on_page
Number of seconds visitor has stayed on current page


@visitor_time_on_site
Number of seconds visitor has stayed on your site


stillOnSite
Delay (in secs) before checking next condition


stillOnPage
Delay (in secs) before checking next condition

Visitor location

Type
Description


@visitor_ip
IP address of the visitor (xxx.xxx.xxx.xxx)


@visitor_hostname
Host name of visitor's IP address


@visitor_city
City the visitor is from


@visitor_region
Region the visitor is from


@visitor_country_code
Two-letter country code of visitor


@visitor_country_name
Country the visitor is from

Previous visit information

Type
Description


@visitor_previous_visits
Number of times visitor previously visited. New visits = 0


@visitor_previous_chats
Number of times visitor chatted with agents. New chats = 0

Page information

Type
Description


@visitor_page_url
URL of the page the visitor is currently on


@visitor_page_title
Title of the page the visitor is currently on


@visitor_page_count
Number of pages visitor has viewed. First page = 1


@referrer
URL of the previous page visitor was on

Visitor information

Type
Description


@visitor_name
Name of the visitor


@visitor_email
Email of the visitor


@visitor_referrer
Referrer URL of the visitor (when they entered your site)


@visitor_search_engine
Referring search engine, if applicable


@visitor_search_terms
Referring search term, if applicable


@visitor_tags
Name of tag (set by the action Set Tag)


@visitor_triggered
'true' if visitor has been triggered (set by the action Set Triggered)


@visitor_department_id
Visitor's department (set by the action Set Visitor Department or by Javascript API)

Visitor software/computer

Type
Description


@visitor_user_agent
Visitor's browser user-agent string


@visitor_browser
Visitor's browser


@visitor_platform
Visitor's operating system/platform

Online statuses

Type
Description


@account_status
Status of your account (online/away/offline)


@visitor_status
Status of the visitor (online/idle/offline)

Chat-related information

Type
Description


@visitor_requesting_chat
'true' if visitor is requesting chat


@visitor_served
'true' if visitor is currently served by agents


@department
Department (name) that visitor chooses on the chat request form


@visitor_served
'true' if visitor is currently served by agents


@sender
Name of the sender of the message


@sender_type
Either 'agent' or 'visitor'


@message
The message being sent

Trigger actions

Action
Parameters
Description


sendMessageToVisitor
Name of agent and message (string)
Sends a message to visitor


setTriggered
True/false (boolean)
Sets the "triggered" flag of the visitor


wait
Duration (in secs) (number)
Waits for specified number of seconds, then performs the next action in the list if the visitor is still online


addTag
Tag Name (string)
Adds a tag to the visitor, which is visible on the dashboard Visitor List


removeTag
Tag Name (string)
Removes a tag from the visitor's session


banVisitor
Reason (string)
Ban visitor with reason


banIp
Reason (string)
Ban visitor's IP address with reason


setName
Name of Visitor (string)
Sets the name of the visitor


setDepartment
Department ID (number)
Set's the visitor's current department


setNote
Note (string)
Sets a note for the visitor, which is visible in the dashboard and is persistent


appendNote
Note (string)
Appends note to end of visitor's current note

Get all triggers GET /api/v2/triggers Lists all the triggers of an account. Allowed for Owner
Administrator
Using cURL curl href="https://www.zopim.com/api/v2/triggers"https://www.zopim.com/api/v2/triggers \ -v -u {email_address}:{password} Example Response HTTP/1.1 200 OK Content-Type: application/json [ { "name" : "Good Trigger", "enabled" : 1, "description" : "Visitor entered page" }, { "name" : "Better Trigger", "enabled" : 1, "description" : "Visitor requested chat" } ] Get a Trigger GET /api/v2/triggers/{trigger_name} Allows an account owner/administrator to retrieve a trigger by name. Allowed for Owner
Administrator
Using cURL curl href="https://www.zopim.com/api/v2/triggers/%7Btrigger_name%7D"https://www.zopim.com/api/v2/triggers/{trigger_name} \ -v -u {email_address}:{password} Example Response HTTP/1.1 200 OK Content-Type: application/json { "name" : "Good Trigger", "enabled" : 1, "description" : "Visitor requested chat", } Create Trigger POST /api/v2/triggers Allows an account owner/administrator to add a trigger to an account. Allowed for Owner
Administrator
Using cURL curl href="https://www.zopim.com/api/v2/triggers"https://www.zopim.com/api/v2/triggers \ -d '{ "name" : "Good Trigger", "enabled" : 1, "description" : "Visitor requested chat" }' \ -v -u {email_address}:{password} \ -X POST -H "Content-Type: application/json" Example Response HTTP/1.1 201 Created Content-Type: application/json { "name" : "Good Trigger", "enabled" : 1, "description" : "Visitor requested chat", } <!-- Example Trigger Definition using cURL Proactive Chat
Automatically send a message of our choice to a visitor who's been browsing through your website for 20 seconds
curl https://www.zopim.com/api/v2/triggers \ -d '{ "name" : "Proactive Chat", "enabled" : 1, "description" : "Proactive Chat for Visitors", "definition" : { "event" : "page_enter", "condition" : [ "and", [ "eq", "@visitor_requesting_chat", false ], [ "eq", "@visitor_served", false ], [ "stillOnSite", 20 ] ], "actions" : [ [ "sendMessageToVisitor", "Zopim Agent", "Hi there, welcome to our website" ], [ "setTriggered", true ] ] } }' \ -v -u {email_address}:{password} \ -X POST -H "Content-Type: application/json" --> Targeting messages to a specific page/directory Sends an automated message to a specific URL or a directory curl href="https://www.zopim.com/api/v2/triggers"https://www.zopim.com/api/v2/triggers \ -d '{ "name" : "Stripe Shoe", "enabled" : 1, "description" : "Send discount code for Stripe Shoe", "definition" : { "event" : "page_enter", "condition" : [ "and", [ "icontains", "@visitor_page_url", "stripshoe" ], [ "stillOnPage", 20 ] ], "actions" : [ [ "sendMessageToVisitor", "Timmy", "We have a discount code for you! Use DISCOUNT10 on your next checkout" ] ] } }' \ -v -u {email_address}:{password} \ -X POST -H "Content-Type: application/json" For detailed configuration of Triggers, go to account's Trigger page Update Trigger PUT /api/v2/triggers/{trigger_name} Allows an account owner/administrator to update the data of a trigger. Allowed for Owner
Administrator
Using cURL curl href="https://www.zopim.com/api/v2/triggers/%7Btrigger_name%7D"https://www.zopim.com/api/v2/triggers/{trigger_name} \ -d '{ "name" : "Best Trigger", "description" : "Visitor requested new chat" }' \ -v -u {email_address}:{password} \ -X PUT -H "Content-Type: application/json" Example Response HTTP/1.1 200 OK Content-Type: application/json { "name" : "Best Trigger", "enabled" : 1, "description" : "Visitor requested new chat", } Delete Trigger DELETE /api/v2/triggers/{trigger_name} Allows an account owner/administrator to delete a trigger. Allowed for Owner
Administrator
Using cURL curl href="https://www.zopim.com/api/v2/triggers/%7Btrigger_name%7D"https://www.zopim.com/api/v2/triggers/{trigger_name} \ -v -u {email_address}:{password} -X DELETE Example Response HTTP/1.1 204 OK Content-Type: application/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"
}
}
