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 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 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 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",
}
Targeting messages to a specific page/directory
Sends an automated message to a specific URL or a directory
curl 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 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 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
1 comment
CS Asev Revanzki
Hi, I tried to create new triggers using API but it seems the `definition` field is ignored by the server.
So what I've done is basically just create empty triggers with different names and had to manually modify all triggers the conditions using Zendesk Chat GUI.
Is it expected? Any workaround?
0