Zendesk Support placeholders are containers for dynamically generated ticket and user data. The format is a data reference contained within double curly brackets. Since you can also access ticket and user data when defining programming logic, it may be helpful to think beyond placeholders and think instead of data objects and their properties that can be used for either purpose.
There are two primary data objects in Zendesk Support: Ticket and User. Each has its own set of properties; the User object, for example, contains user properties such as name and email. In addition to these two data objects, there are associated data objects. For tickets, there are the Comment and Satisfaction Rating objects. For users, there are the Organization and Agent objects.
Although placeholders can be in HTML format, when a placeholder is sent to a HTTP or URL target, Markdown is used to render the placeholder, not HTML.
Support includes inborn system rules that suppress placeholders in triggers in certain situations. Inborn system rules are rules that you cannot change, modify, or override, which dictate the default behavior of Support. These rules may sometimes make it seem like placeholders in triggers failed to work, but this isn’t a mistake. These rules protect you because they prevent spammers from using your account to distribute spam messages. For more information, see Understanding placeholder suppression rules.
This article categorizes the placeholders by the data they display:
- User data
- Organization data
- Agent data
- Ticket data
- Comment data
- Satisfaction rating data (Professional and Enterprise)
Related articles:
User data
- ticket.requester, who is the person who requested the ticket
- ticket.assignee, who is the agent assigned to the ticket
- ticket.submitter, who is either the user who submitted the request or the agent that opened the ticket on behalf of the requester
- current_user, who is the user currently updating the ticket (an end-user or agent)
This means that most of the user data listed in the following table can be returned for each type of user (for example, {{ticket.submitter.name}}, {{current_user.name}}, and so on).
Properties/placeholders | Description |
---|---|
user.name
Important: Remember to replace user with one of the user types shown above (for example, ticket.requester).
|
The user's full name. |
user.first_name | The user's first name. |
user.last_name | The user's last name. |
user.email | The user's email address. |
user.language | The user's language preference. |
user.phone | The user's telephone number. |
user.external_id | The user's external ID (if one exists). Optional for accounts that have enabled enterprise single sign-on using JWT or SAML. |
user.details | The user's details. |
user.notes | The user's notes. |
user.time_zone | The user's time zone. |
user.role | The user's role (Admin, Agent, or End-user). |
user.extended_role | When using Zendesk Support Enterprise agent roles, this returns the name of the agent's Enterprise role. These are the predefined roles:
If you've created custom agent roles, those role names are returned. If you're not an Enterprise account, using this placeholder returns 'Agent' for all agent users. End-users are 'End-user'. For more information about custom agent roles, see Custom agent roles. |
user.id | The user's ID. |
user.locale | The user's locale (for example: en-US). |
user.signature | The agent's signature. Only agents have signatures. |
user.organization... | See Organization data below. |
user.tags | Tags. See Adding tags to users and organizations. |
Organization data
Each type of user can be added to an organization. An organization contains the following data properties.
Properties/placeholders | Description |
---|---|
user.organization.id
Important: Remember to replace user with one of the user types shown below.
|
The ID of the organization that the user is assigned to. |
user.organization.name | The name of the organization that the user is assigned to. |
user.organization.is_shared | True or False. Indicates if the organization is a shared organization. |
user.organization.is_shared_comments | True or False. Indicates if the organization allows users to add comments to other user's tickets. |
user.organization.details | Details about the organization. |
user.organization.notes | Notes about the organization. |
user.organization.tags | Tags. See Adding tags to users and organizations. |
- {{ticket.organization.name}}, which is the ticket requester's organization
- {{ticket.requester.organization.name}}, which the same as {{ticket.organization.name}} (the requester)
- {{current_user.organization.name}}, who is the user currently updating the ticket (an end-user or agent)
- {{ticket.assignee.organization.name}}, who is the agent assigned to the ticket
- {{ticket.submitter.organization.name}}, who is either the user who submitted the request or the agent that opened the ticket on behalf of the requester
Agent data
You can use the following placeholders in agent signatures only. For information on agent signatures, see Adding an agent signature to ticket email notifications.
Properties/placeholders | Description |
---|---|
agent.name | The agent's full name (or alias, if present). |
agent.first_name | The agent's first name. |
agent.last_name | The agent's last name. |
agent.role | The agent's role. |
agent.signature | The agent's signature. |
agent.email | The agent's email address. |
agent.phone | The agent's phone number. |
agent.organization | The agent's organization. |
agent.language | The agent's language. |
agent.time_zone | The agent's time zone. |
Ticket data
Zendesk Support tickets contain the following data properties.
Properties/placeholders | Description |
---|---|
ticket.account | The Zendesk account name. |
ticket.assignee.name | Ticket assignee full name (if any). See User data above. |
ticket.brand.name | The ticket's assigned brand name. |
ticket.cc_names | Returns the names CCs on the ticket.
Note: If you are using the new CCs and followers experience and you are adding or updating your placeholders, we recommend using
ticket.email_cc_names instead of tickets.cc_names . They do the same thing.If you want to return the email addresses of the people CC'd on the message, you can use this Liquid code:
|
ticket.email_cc_names |
With the new CCs and followers experience, returns the names of CCs on the ticket. With the old CCs experience, returns empty.
Note: If you are using the new CCs and follower experience and you are adding or updating your placeholders, we recommend using
ticket.email_cc_names instead of tickets.cc_names . They do the same thing. |
ticket.follower_names | With the new CCs and followers experience, returns the names of followers. With the old CCs experience, returns empty. |
ticket.follower_reply_type_message | With the new CCs and followers experience, indicates what type of comment (public or private) triggered the notification. With the old CCs experience, returns empty. |
ticket.created_at | Date the ticket was created (for example, May 18, 2014).
Note: The year is not included if the ticket was created in the current year.
|
ticket.created_at_with_timestamp | Time the ticket was created expressed as an iso8601 format date/time. Example: 2013-12-12T05:35Z, which translates to December 12th, 2013 at 05:35am UTC. |
ticket.created_at_with_time | Date and time the ticket was created. For example, February 10, 14:29. |
ticket.current_holiday_name | If the placeholder is used outside of a holiday, it is null. If it is used within a holiday, the holiday's name is displayed. If you've set up multiple schedules, this placeholder respects the list of holidays set in the schedule applied to the ticket. |
ticket.description | The ticket description (the first comment), the agent's name, and the comment date.
Note: If the subject field is empty or not visible to the requester, then this first comment will be used and sent to the requester. This is true for private tickets as well.
|
ticket.due_date | The ticket due date (relevant for tickets of type Task). The format is: May-18. |
ticket.due_date_with_timestamp | The ticket due date (relevant for tickets of type Task) expressed as an iso8601 format date/time. Example: 2013-12-12T05:35+0100 which translates to December 12th, 2013 at 06:35am UTC+1. |
ticket.external_id | The external ticket ID (if one exists). |
ticket.encoded_id | The encoded ID is used for threading incoming email replies into existing tickets. |
ticket.group.name | The group assigned to the ticket. |
ticket.id | The ticket ID. #{{ticket.id}} creates a clickable link. {{ticket.id}} renders the ticket number in plain text. |
ticket.in_business_hours | True or False. True if the ticket update is during business hours. See Setting your business hours. |
ticket.link | Full URL path to ticket. |
ticket.organization.custom_fields.<key_name> | Property/placeholder format for custom organization fields. See Adding custom fields to organizations. |
ticket.organization.custom_fields.<field_key>.title | Property/placeholder format for the option title of a custom organization drop-down field. See Adding custom fields to organizations |
ticket.organization.external_id | External ID of the ticket requester's organization. |
ticket.organization.name | See Organization data above. |
ticket.priority | The ticket priority (Low, Normal, High, Urgent). |
ticket.requester.name | Ticket requester full name. |
ticket.requester.custom_fields.<key_name> | Property/placeholder format for custom user fields. For example, {{ticket.requester.custom_fields.my_custom_field}}. See Adding custom fields to users. |
ticket.requester.custom_fields.<field_key>.title | Property/placeholder format for the option title of a custom user drop-down field. For example, {{ticket.requester.custom_fields.manager_for_approval.title}}. See Adding custom fields to users. |
ticket.status | The ticket status (New, Open, Pending, Solved, Closed). |
ticket.tags | All of the tags attached to the ticket. |
ticket.ticket_field_<field ID number> | Property/placeholder format for custom fields. For example, {{ticket.ticket_field_123}}. See Placeholders for custom fields. |
ticket.ticket_field_option_title_<field ID number> | Property/placeholder format for the option titles of a drop-down custom field. For example, {{ticket.ticket_field_option_title_456}}. See Placeholders for custom fields. |
ticket.ticket_form | Form name for end-users. |
ticket.ticket_type | Ticket type (Question, Incident, Problem, Task). |
ticket.title | The ticket subject. |
ticket.updated_at | Date the ticket was last updated (for example, May18). |
ticket.updated_at_with_time | Time and date the ticket was last updated. For example, February 10, 14:29. |
ticket.updated_at_with_timestamp | Time the ticket was last updated expressed as an iso8601 format date/time. Example: 2013-12-12T05:35Z, which translates to December 12th, 2013 at 05:35am UTC. |
ticket.url | The full URL path to the ticket (excluding "http://"). |
ticket.verbatim_description | The plain text value of the ticket decription (the first comment). |
ticket.via | The source type of the ticket (Web form, Mail, Twitter, etc.). |
account.incoming_phone_number_ID | Zendesk Talk inbound phone number. For example,{{account.incoming_phone_number_123}}. |
Comment data
-
Standard objects allow you to use liquid hashes to pick and choose what you want to display, and return a collection of comment and attachment data. For example, you can set up templates to iterate over comments using
{{ticket.comments}}
. -
Formatted objects allow you to return preformatted, rendered HTML representations of the standard placeholders, but without a large degree of customization. They simply return comments in predefined formats. For example,
{{ticket.comments_formatted}}
returns a chunk of rendered HTML. The ticket comments will include dates, author, the author’s avatar, and the like. - Rich text objects allow you to use rich text in your customized template (as with the formatted object placeholders) without being restricted to the predefined formatting rules, so you can have more control over the look and feel of your notifications. However, rich text objects do not allow you to include attachments.
Properties/placeholders | Description |
---|---|
ticket.comments | Used as a placeholder, {{ticket.comments}} displays all the comments in a ticket in unformatted text.
Note: Agents will receive both public comments and internal notes; end-users will receive only public comments.
Ticket.comments also serves as a collection for comment and attachment details. You can access the following data using Liquid markup:
For an example of accessing this data in business rules, see Customizing the formatting and placement of text in comments and email notifications.
Note: This same comment data collection is available when using the ticket.public_comments, ticket.latest_comment, and ticket.latest_public_comment placeholders.
|
ticket.public_comments | All public comments, most recent first. Unformatted text. |
ticket.latest_comment | The most recent comment. Unformatted text. Does not include attachments, unless Include attachments in email is enabled. To return attachments, use ticket.latest_comment_formatted.
Note: Agents will receive the most recent public comment or internal note; end-users will receive the most recent public comment.
|
ticket.latest_public_comment | The most recent public comment. Unformatted text. |
Properties/placeholders | Description |
---|---|
ticket.comments_formatted | All comments, most recent first.
Note: Agents will receive both public comments and internal notes; end-users will receive only public comments.
|
ticket.public_comments_formatted | All public comments, most recent first. |
ticket.latest_comment_formatted | The most recent comment including any attachments.
Note: Agents will receive the most recent public comment or internal note; end-users will receive the most recent public comment.
|
ticket.latest_public_comment_formatted | The most recent public comment. |
Properties/placeholders | Description |
---|---|
ticket.latest_comment_rich |
The most recent comment. Rich text formatting. Does not include attachments, unless Include attachments in email is enabled.To return attachments, use ticket.latest_comment_formatted.
Note: Agents will receive the most recent public comment or internal note; end-users will receive the most recent public comment.
|
ticket.latest_public_comment_rich | The most recent public comment. Rich text formatting |
Satisfaction rating data (Professional and Enterprise)
Properties | Description |
---|---|
satisfaction.rating_section | A formatted block of text prompting the user to rate satisfaction. |
satisfaction.rating_url | A URL to rate the support. |
satisfaction.current_rating | The text of the current satisfaction rating (e.g. "Good, I am satisfied"). |
satisfaction.positive_rating_url | A URL to rate the support positively. |
satisfaction.negative_rating_url | A URL to rate the support negatively. |
satisfaction.current_comment | The comment that the user added when rating the ticket. |
199 Comments
In my Zendesk account, the "ticket.requester" placeholders are defaulting to the submitter's info on new tickets if the requester field hasn't been populated. For example, if I select a macro that uses the {{ticket.requester.first_name}} placeholder and I haven't populated the requester, the comment text will show "Jason". Is this happening with anyone else?
Is there a placeholder for the Brand? We have been looking for one with no success. If the ticket has a brand and tickets come in with a brand, wouldn't there be a placeholder somewhere for it?
Nevermind.. {{ticket.brand}}
Hello,
Could you please point me, on where to find a placeholder for the second email of the current user. The primary one is {{current_user.email}}, but I need as well a placeholder for the second email attached to the agent.
Thanks
Tsvetan
@Tsvetan unfortunatly there isn't a placeholder for the other email adresses for a user in Zendesk with standard placeholders... You should be able to retrieve the emails via the User Endpoint in the API, but im not sure if that would solve your problem...
Thanks for the reply @Carsten, but yes, this is not my case. It is quite annoying that you can enter second or third emails to an Agents, but then you can't use these as a placeholder. We have different brands for which our Agents have different signatures, with different email addresses and we are applying these through Macroses. Now it seems that we should configure private Macroses per single agent ...
@Tsvetan I think you can write an app, that lets you switch email address... That should be possible...
Thanks @Tamara (Field) for the info provided on placeholders for custom ticket fields.
would be great to have a placeholder that showed you, in a trigger based email, what the update to a ticket is as you see it in "show all events" - the most recent event(s).
Hello,
Is it possible to make a placeholder for logmein remote control link?
Thank you
Can I use fallback? For example:
Hi {{requester.first_name|fallback:"there"}},
Allen,
Normally, you would set up something like:
The problem is that the requester info defaults to the current user when the requester field is blank, so the above if statement can never evaluate as true. As a sort of work around, you can compare the requester and current user IDs, instead:
Assuming that you are trying to use this in a macro, this code will check if the ID of the person applying the macro is the same as the ID of the person set as the requester, which will be true if the requester field is blank.
You can do some other things with the code, too, like passing through the placeholder:
If the requester field is blank, the comment box will show "Hi {{ticket.requester.first_name}},". Then, when the agent populates the requester field and submits the ticket, the placeholder will be replaced with the requester's first name.
@Jason - great tip. I particularly like the use of the {% raw %}
It would be great if there was a way to create a placeholder for the cursor in text boxes. So, if I have a template the cursor will be placed in the right location to continue typing your reply. This would be useful, for example, with this type of simple macro...
Hi {{ticket.requester.first_name}},
{{cursor}}
If you have any further questions please reply to this email, thanks.
The above would place the cursor between the two lines of text so I can just start typing without having to move the cursor to the right location first. This would be especially useful with the Zendesk smartphone app. Also, it seems that the macros collapse more than two line-feeds into one, so, I also have to add extra line feeds into the template to separate the top and bottom line.
Strange problem we cant solve... I have this in our "comment update" trigger:
{{ticket.account}}: Ticket ({{ticket.id}}) Re: {{ticket.title}}
For some reason in the subject line that customers receive from us, it puts the following:
(Company name), (Ticket number), which is fine, but then it places the subject line and the body of the message all in the subject line, until the character limit is reached and it cuts it off.
If I remove this from the subject line on that same trigger: Re: {{ticket.title}} it stops putting the subject and the body.
Why is it not just putting the ticket title? Why is it also adding the whole body of the email in the subject line?
Hey Thor,
Can you check to confirm that the "Subject" ticket field is set as "visible" for your End-Users? If it's not visible it'll default to using the first part of the ticket comment.
That did the trick! Thanks Nick!
Hi,
Is there or will there be a place holder for the original email/ticket sent like ticket.original_email?
I am looking for a way to exclude any conversation on a ticket when I need to assign the ticket to an external light agent that only needs the original email/ticket submitted in order to respond with the solution that I can relay to the requestor.
Paul
@Paul: I also replied to the ticket you submitted on this topic, but just to cover all our bases - the placeholder you're looking for is ticket.description.
If you have any additional questions on this topic just drop me a line in that ticket and I'll be happy to help :)
I had a support ticket about the Formatted comment data recently, and just wanted to clarify, if any one else tries this, that the formatted comment data objects - like ticket.comments_formatted - has no properties, so you cannot iterate or query it's properties with liquid markup, as you can with the comment data object like ticket.comments.
I attempted to hack away the comment timezone problem with the following Liquid, it's based on the assumption that comment created_at is recorded in the same timezone that ticket was – which I'm 98% sure isn't true (see https://support.zendesk.com/hc/en-us/community/posts/203413956-Timezone-information-for-Ticket-comments) but it seems to work in my experiments at least.
{% capture offset %}
{% assign offset_neg = ticket.created_at_with_timestamp | split: '-' | last %}
{% assign offset_pos = ticket.created_at_with_timestamp | split: '+' | last %}
{% if offset_neg contains 'T' %}
+{{ offset_pos }}
{% else %}
-{{ offset_neg }}
{% endif %}
{% endcapture %}
{% assign offset = offset | strip_newlines | replace: ' ', '' %}
"created_at": "{{ comment.created_at_with_time | date: "%Y-%m-%dT%H:%M:%S" }}{{ offset }}"
How about placeholder for submitter's location, country, IP?
Hi all,
Sorry if this has already been put in here and I missed it - I'm looking to place the URL of our Help Center behind text into the auto-replies that are sent out at ticket creation, and I can't seem to figure out how.
Currently, I seem to only be able to add the link as a bare URL in the following fashion:
"We encourage you to browse our robust Knowledge Base for detailed product documentation, helpful pro tips, and much more: https://support.mycompany.com"
I know placing the URL behind text *can* be done since I see it done in the auto-replies I get from Zendesk when I log a ticket. Hopefully I'm missing something really simple?
Thanks!
Can we use placeholder in macro to set subject ?
@Manuel - Unfortunately there are no placeholders for those items, as they are not tied to the user object or ticket object (technically they are part of the ticket updates). If you want to store that information yourself in a custom ticket or user field, you can then use a placeholder. Keep in mind that user.time_zone and user.locale are available.
@Diana - What you're looking for is Markdown - special formatting syntax will allow you to make text into a link (among other things)
@Ravi - Yes, that will work. If you're having problems, drop us a line at support@zendesk.com
We use the ticketing system from a 3rd party application. We have fields like "source", "identifier", and "description". Is there a way to parse the values of these into a macro?
Source : pem:1/1
Identifier : null
Raise Time : 2016-05-08T10:31:46.000Z
Clear Time : null
Description : Environment temperature above high threshold
Not sure if the following information is correct.. I'm able to get attachments using ticket.latest_comment.attachments and unable to see them using ticket.latest_comment_formatted.attachments. I'm using this placeholder in a trigger json body.
The doc says there are two attributes available to use from an attachment:
comment.attachments
Can we not retrieve other attributes including content_type of the attachment ?
Hi! I don't see a placeholder for the Help Center URL, but I think that would be a good one to add. Especially in the case where one trigger may be used for multiple brands with different Help Center URLs.
It seems like it'd be simple, since when using {{ticket.link}} it correctly fills the corresponding Help Center URL.
I'm happy to re-submit this feedback elsewhere that might be more appropriate. Let me know where to do that. Thanks!
Elizabeth
We can have some fun with Liquid to create a help centre link.
Try this in a macro:
Are there any NPS placeholders?
Please sign in to leave a comment.