Zendesk chat and messaging triggers allow you to add information about your customers, improve workflow routing, and handle spam requests.
For more information about triggers, see Zendesk Chat triggers resources.
This article contains the following tables:
Selecting run events for chat and messaging triggers
When you create a trigger, you must select a run event. These events determine whether that trigger will run, check its conditions, and perform its defined actions. Run events are selected when creating a trigger using the Run trigger drop-down.
Firing event | Description |
---|---|
When a visitor has loaded the chat widget | Runs the trigger when the chat widget appears on the page but
the visitor hasn't interacted with it.
Note: Selecting this
firing event overrides pre-chat forms. To continue using your
pre-chat form, use other firing events.
|
When a visitor requests a chat | Runs the trigger when the visitor requests a chat. |
When a chat message is sent | Runs the trigger when the visitor has sent text in the chat widget. |
Building chat and messaging trigger condition statements
Condition statements consist of conditions, field operators, and condition values (these vary depending on the condition selected). Condition statements are essentially ‘if’ statements that return 'true' values that meet the specified criteria. When 'Check All of the Following Conditions' is selected, the first condition statement that evaluates to false terminates the trigger. When 'Check Any of the Following Conditions' is selected', only one condition needs to be true for the actions to fire.
Condition | Description |
---|---|
Time/Date | |
Hour of day | Hour of the Day (Universal Time Clock): 0 = Midnight 23 = 11 p.m. Note that the Hour of day condition uses the hour only, and does not include minutes. |
Day of week | Day of the Week: 0 = Monday 6 = Sunday |
Still on site | A condition check of whether the user is still on the
domain after X seconds since the scenario chosen has
elapsed. Max 3600 seconds |
Still on page | A condition check of whether the user is still on the same
page after X seconds since the scenario chosen has
elapsed. Max 3600 seconds |
Location of visitor | |
Visitor IP | IP address of visitor |
Visitor host name | Host name (domain) associated with the visitor's IP address |
Visitor city |
City name associated with the visitor's IP address |
Visitor region |
Region the visitor is from, according to GeoIP. For the US and Canada, we use the ISO-3166-2 regions. These are the different states (e.g. Vermont). For everywhere else, we use the FIPS 10-4 standard. The GeoIP website has a CSV file which lists all the different regions: http://www.maxmind.com/download/geoip/misc/region_codes.csv |
Visitor country code | Two-letter country code of the visitor's IP address. Codes are case-sensitive and should be upper-case. |
Visitor country name | Country name associated with the visitor's IP address |
Previous visit information | |
Visitor previous visits | Number of previous independent visits: 0 = First time
visit Max value 2.1 million |
Visitor previous chats | Number of previous independent chats initiated with an agent: 0 = First time chatter |
Page information | |
Visitor page URL | Current URL of visitor (Widget must be installed on this page) |
Visitor page title | Current title of page visitor is on (Widget must be installed on this page) |
Visitor page count | Number of pages visitor has viewed. First page = 1 |
Previous page | URL of the previous page the user was on. |
Visitor information | |
Visitor name | Name of visitor |
Visitor email | Email of visitor |
Visitor referrer | Referrer URL of visitor, if applicable, determined from content headers |
Visitor search engine | Referring search engine, if applicable. Note that these
values are case-sensitive and should be
lowercase: yahoo bing yandex |
Visitor search terms | Referring search terms, if applicable |
Visitor tag | Tag (Applied via Set Tag action) |
Visitor triggered | Triggered visitor (activated by Set Triggered action). Select
either of the following from the drop-down
menu: True False |
Visitor department | Visitor's department, set by the action Set visitor department or Javascript API. |
Software/Computer of visitor | |
Visitor user agent | Visitor's user agent string |
Visitor browser | Browser used by visitor |
Visitor platform | Platform used by visitor |
Online statuses | |
Account status | Status of your Zendesk Chat account which works as a
hierarchy
system. Online Away Offline
|
Department status |
Status of the selected Zendesk department. Online Away Offline |
Visitor status | Status of Visitor: Online Idle (no mouse or keyboard movement in the chat window for 10 minutes) |
Chat-related information | |
Visitor is chatting | 'true' if the visitor is currently in an active chat session. |
Visitor requesting chat | 'true' if the visitor is requesting a chat by hitting
Send in their chat message. 'false' if the visitor is not requesting a chat. |
Visitor served | 'true' if the visitor is currently being served by an agent (for
instance, an agent has opted to serve the customer and has sent
their first message in the chat). 'false' if an agent has not sent a response to the visitor. |
Sender | Name of sender of the chat message |
Sender type | Type of sender. Note that these values are case-sensitive and
should be
lowercase: visitor agent |
Message | The message being sent |
Department | Department (name) that visitor chooses from the pre-chat form |
Visitor queue | |
Queue size (account) | Total number of incoming chat requests for the account. Note that the condition targets the total account queue, and does not measure the department queue. |
Operators for trigger condition statements
Use the following operators to build trigger condition statements.
Operator | Description |
---|---|
Equals | Exact match
|
Less than | Less than the number entered, but not including
|
Greater than | More than the number entered
|
Less than or equal to | An exact match or less than the number entered<= 3 returns true on a 3, 2, 1, or 0 |
Greater than or equal to | An exact match or more than the number entered
|
Is not equal | Anything but the value entered
|
Contains | String includes the following text
|
Does not contain | String does not include the following text"help" matches true with "not just anybody" |
Reg Ex | Matches for regular expression values using the Python RegEx
framework. This field looks for a full
match, not a partial. For assistance, you can use Pythex as a quick-reference and
validation tool.
|
Building chat and messaging trigger action statements
Action statements define what occurs if all the condition statements are true and the trigger fires. You can think of action statements as ‘then’ statements: if all of your conditions are true, then perform these actions to update the user and optionally send notifications.
Action | Description |
---|---|
Send Message to visitor | Sends the given message to the visitor
Note: If the account is
offline, this action will not work.
|
Set triggered | Set Triggered can be one of two values and applies a flag
which can be used in conjunction with the 'Visitor Triggered?'
condition. Select one of the following from the drop-down
menu:
Note: If the account is offline, this action will not
work.
|
Wait | Delay (in seconds) before the next action fires
Note: If you
have multiple triggers that must be executed in a certain
order, you need to add at least one second of wait time
between each trigger. This is required due to the fact that
triggers do not run in a particular order and are evaluated
and executed simultaneously.
|
Add tag | Adds a tag to the ticket |
Remove tag | Removes a tag from the ticket |
Set name of visitor | Sets the visitor's name |
Set visitor department | Adds a department to the visitor profile. When this action is selected, a drop-down menu appears, allowing you to select an available department. Only works when Run trigger is set to When a visitor has loaded the chat widget. |
Replace note | Replaces the note of the visitor's profile |
Append note | Adds to the note of the visitor's profile |
Block visitor | Bans the visitor from accessing your chat service. See Banning visitors from accessing Chat for more information on blocking visitors. |
Request email (continuous conversations) | Messaging-related action. Sends automated message to visitor requesting an email for continuous conversation re-engagement. See Enabling continuous conversations to re-engage messaging customers for more information. |
Request messaging rating | Messaging-related action. Sends automated satisfaction survey at the end of a conversation. See About the CSAT (customer satisfaction) user experience for email and messaging. |
Using placeholders in chat and messaging trigger action statements
Placeholders are references to visitor details you can use in trigger action statements. When the trigger is fired, the placeholder pulls in the current visitor and session information.
Placeholder | Type | Description |
---|---|---|
@hour_of_day | Integer | Current hour of the day (UTC timezone). 0 - 23 |
@day_of_week | Integer | Current day of the week (0 = Monday, 6 = Sunday) |
@visitor_ip | String | City the visitor is from (based on IP address) |
@visitor_hostname | String | Host name of the visitor's IP address |
@visitor_city | String | Visitor's city |
@visitor_region | String | Region the visitor is from (based on IP address) |
@visitor_country_code | String | Two-letter country code of where the visitor is from (based on IP address). Codes are case-sensitive and should be upper-case. |
@visitor_country_name | String | Country the visitor is from (based on IP address) |
@visitor_page_url | String | URL of the page the visitor is currently on |
@visitor_page_title | String | Title of the page the visitor is currently on |
@visitor_referrer | String | Visitor's referral URL |
@visitor_search_engine | String | Search engine the visitor used to find your website (can be blank) |
@visitor_search_terms | String | Search terms the visitor used to find your website (can be blank) |
@visitor_user_agent | String | Visitor's browser User-Agent string |
@visitor_browser | String | Visitor's browser |
@visitor_platform | String | Adds to the note of the visitor's profile |
@account_status | String | Status of your account (online, away, or offline) |
@visitor_previous_visits | String | Number of previous independent visits |
@visitor_previous_chats | String | Number of previous independent chats inititated with agent |
@visitor_name | String | Name of visitor |
@visitor_status | String | Visitor status (online, idle, or offline) |
@visitor_time_on_page | String | Visitor's time spent on current page |
@visitor_time_on_site | String | Visitor's time spent on site during current log in |
@visitor_page_count | String | Number of pages viewed by visitor |
@visitor_requesting_chat | String | True if visitor requested chat |
@visitor_served | String | True if visitor is currently being served by an agent |
@visitor_tags | String | Tags applied to visitor |
@visitor_triggered | String | Triggered visitor (true or false) |
@referrer | String | The URL where the visitor's current session originated |
45 comments
SendSafely Agent (BH)
Is there a way to show/print the session ID of the current chat session using a placeholder?
0
Brett Bowser
Hey BH,
I double checked and it doesn't look like there's an available placeholder for session ID at this time.
Let us know if you have any other questions!
0
Nathan Purcell
@... does the visitor page url include the domain?
0
Jess Bertubin
Currently the visitor name placeholder pulls in full name. Is it possible to have a placeholder that breaks out the visitor's name into first name and last name?
1
Matt
Hey @...
The visitor page url includes the full URL of the visitor.
For example https://subdomain.zendesk.com/hc/en-us
Hey @...
That is a good question! Since the visitor only enters a name (not a first and last name) when starting a chat, we currently only have a placeholder to reference the full name that the visitor entered.
Let us know if you have any further questions!
0
Jürgen König
I miss an email notification as a trigger action to any person mail address (e.g. alert if chat requester waits too long) or similar.
0
Dane
Are you pertaining to chat triggers sending email notifications to the chat requesters? If that's the case, this feature is not supported on chat triggers.
If I misunderstood your concern, feel free to respond and I'll look into it for you.
Cheers,
Dane
0
Jürgen König
Hello Dane, thank you for an answer. Unfortunately this does not solve the problem. I am searching for a solution to inform (anyhow: mail, ticket, alarm, ...) on basis of an event by a trigger action. Background: No automatic creation of a support ticket by a chat available. Regards, Jürgen
0
Chad Susa (Gravity CX - Zendesk Partner)
Hi
Is there a way to reset/remove the previous triggered comment in the chat widget?
Our scenario is that we have multiple pages for Ready to Ship items. We want a trigger to pop-up the chat widget with a message saying 'These items are ready to ship, Chat with us now'.
Problem is, we have multiple Ready to Ship pages and each page has a trigger (only fires once per visitor) saying the same thing.
So the customer experience is that the widget pops-up with the previous trigger message in view - looks kind of silly.
Was wondering if there is a way to 'reset' the chat widget window to blank (no history)?
See example screenshot:
0
Charles Gresula
Hi Chad Susa (Gravity CX - Zendesk Partner)

I am afraid it is not possible yet to clear/reset the chat widget but maybe you can use tags in the conditions and actions of your triggers so that they won't fire on chats where another trigger of the same nature already fired?
0
Gianpaolo Valle
Hi,
in the conditions I don't find the country code, what must be done to enable it?
0
Shalaka Walambe
Hello,
I was wondering if it's possible to set a trigger action based on a page event if the URL remains the same.
E.g. Show proactive trigger if customer encounters errors at checkout due to incorrect phone number format entered.
0
Dane
Hi Gianpaolo Valle,
The option should be on the top part of the condition drop down.
Hi Shalaka Walambe,
As it turns out, the actual widget have no access/visibility on such events. Therefore such conditions/actions is not possible.
0
Chad Susa (Gravity CX - Zendesk Partner)
Hello all :)
Just wondering what the definition of Visitor previous visits "Number of previous independent visits:" is?
How does Zendesk Chat determine / know how many previous independant visits someone has had? I'm guessing it's a cookie somewhere....and therefore if history is cleared, that means they are classed as a New Visitor..
0
Chris Smith
If using Day of week as a condition for messaging chat is unavailable over a weekend, can the condition simply be Greater than 4 or must it also include Less than 0?
0
Dainne Kiara Lucena-Laxamana
Hi Chad Susa (Gravity CX - Zendesk Partner)
It's based on the number of unique sessions created for that visitor_id.
Hi Chris Smith
The "day of week" condition is also available for weekends. 5 is Saturday while 6 is Sunday
0
Nikki
I don't really understand why/when to use the "Visitor Triggered" condition/action. Can I hear some use cases?
ie is it generally used to help us know when the visitor reached out first? Or when we've done a proactive message? Does it reset with each visit or persist with the visitor_id?
And just to confirm: "each visitor will receive this message only once" does persist with visitor_id and if true, they'll only EVER see it once (unless cache reset or whatever)?
0
Dainne Kiara Lucena-Laxamana
Hi Nikki
It actually depends on both the visitor ID & also the session ID. When the chat timeouts or end & then the end-user chats again, the trigger should fire again.
As for the "Visitor Triggered" condition, this would be an example:
fire only once per visitor
" is disabled but you want to fire the trigger every time a visitor reopens the site.So the Visitor Triggered condition & Set Triggered action work hand in hand.
Hope this helps!
0
Nikki
So just to re-state:
When "
fire only once per visitor
" is enabled then Joe Schmoe will only see that message once ever (on that browser / unless cleared cache / etc)Whereas if you want Sally Smith to only see it once for THIS chat, but you want them to see it again the next day when they log in again, then you use condition "visitor triggered is false" and action "set triggered is true."
Additionally, if you want Sally to only see one of three given triggers in a session, then if they get triggered for one, the user is counted as "triggered" and any other triggers with "visitor triggered is false" will not be shown in this chat session.
Is that right?
0
Dainne Kiara Lucena-Laxamana
Hi Nikki!
The chat triggers apply to the whole account so it won't matter which user goes to the website. The trigger "visitor triggered is false" or even the "visitor triggered is true" only works if you have a trigger that has an action set as "visitor triggered is false" or "visitor triggered is true". So it would still depend on your implementation.
Let me know if you have any follow-up questions!
0
Nikki
Dainne Kiara Lucena-Laxamana I think it would help if someone just reviews all of my chat triggers with me! Should I reach out to my account manager or should I speak with you or another chat expert?
0
Dainne Kiara Lucena-Laxamana
Hi Nikki!
I went ahead & created a ticket for you instead. Please keep an eye out for one of our advocate's updates on the ticket so we can help check your chat triggers.
0
Giovanni Landolina
Hi,
is there any way to trigger a webhook call on new chat messages?
0
Dane
Unfortunately, it's not supported on the conditions available for Chat triggers.
It can only be possible for ticket updates for Agent Workspace when a ticket via Chat channel has been updated.
0
Raphaël Péguet - Officers.fr
Hi Zendesk community,
There's no placeholder for the agent name?
Best regards
0
Dane
If you mean conditions specifically for agents, chat triggers don't have that specific condition.
0
Raphaël Péguet - Officers.fr
Hi Dane
No I meant placeholder such as {{agent.name}} in regular Zendesk they exist on chat triggers looking like: @visitor_name (with a "@" structure) doc here
But actually chat macros are obsolete as we can use Support Macros (not chat macros) for chat.
Support macros offer much more flexibility (dynamic contente, tons of place holders)
The issue is that when we want to send an automatic message how come we select the current agent???
0
Dane
I have also checked it directly and it's not part of the trigger placeholders.
0
Anais
Hi,
There is a new condition that isn't explained in this page: "visitor is chatting".
I'm asking because I found that the condition "sender is not agent" does not work. Is it a known issue?
For context, I'm trying to send a specific notification when the customer writes when everyone is offline. Agents sometimes answer chat without being online, and the specific notification gets sent (even though I have the condition "sender is not agent").
1
Saida Mammadova
Hi I'm trying to set a trigger where if the customer does not reply to the agent, an automatic message will be sent after 3 minutes saying something like "Unfortunately we are ending the chat session with you...see you next time".
Why is it not working?
4