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