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:
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 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
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. |
207 Comments
Is there any plan to propose a placeholder dedicated to the rating reason?
Hey Thomas,
Nothing on the roadmap currently. Could you provide some additional context on why you'd need this placeholder available? I'm happy to pass your feedback along to the appropriate team :)
Let me know!
Hey Brett,
Thanks for the quick feedback! But so bad to hear so…
The context is pretty simple: we have triggers and macros that notify the related team once a ticket has a bad rating. To do so, we're using the following placeholders:
We'd like to be able to simply add something like satisfaction.reason. This information is here, I don't see any reason why I wouldn't be allowed to retrieve this helpful information in our triggers and macros. I guess this makes sense ;-)
Thanks!
I have a trigger with Meet ANY of the following conditions:
The action notifies a URL Target with this message:
{
"response": {
"ticketId": "{{ticket.id}}",
"ticketStatus": "{{ticket.status}}",
"latestComment": "{{ticket.latest_public_comment | json}}",
}
This works fine for me if the agent add a comment upon solving the ticket.
If the agent solves the ticket without ever adding a comment, "{{ticket.latest_public_comment | json}}" has all of the customer comments.
If the agent solves the ticket with out adding a comment but has given at least one earlier in the ticket, then "{{ticket.latest_public_comment | json}}" has the agents last comment duplicated.
I need to be able to determine if the agent has actually added a comment on the most recent update. How can I do that?
Can you trigger off 'Comment is Public', 'User is Agent', 'Comment is Present' or similar? Depending what you need, you could have one trigger for if a comment is present and one for if it isn't.
That help?
Hi Andrew,
Thanks for your response! There is no option to say "Comment IS NOT Present". The "Comment" condition only has "is" for the operator.
How do I handle the condition when the ticket is updated but the comment is not present?
Are there any plans to add SLA-related placeholders?
hours_till_next_sla_breach , hours_since_sla_breach , etc.?
We'd like to use such placeholders when notifying agents about impending SLA breaches, and provide the actual number of hours left in the message.
Hey Eitan,
No plans for adding SLA placeholders at this time but I do think this would be super useful! I'm going to pass this feedback along to the appropriate team so they're aware of this need.
In its current state, you'd be limited to using automations to notify your agents of an upcoming breach.
Cheers!
This is what I came up with to make a universally clickable link to the ticket in the initial response email to customers:
If you'd like to send us an update, please reply to this email or you can view <a href="https://{{ticket.url}}">Ticket {{ticket.id}}</a> on the web to add comments or upload attachments.
This article we're commenting on here still lists "ticket.link" (which no longer exists) rather than "ticket.url". Usually a URL includes the protocol or scheme, but ticket.url does not include it.
Appreciating you taking the time to share this with us Bballard! I'll reach out to our documentation team to see if we can get this information updated.
Cheers!
Hi!
Is there a way to copy the formatting of a ticket field when using the ""ticket.ticket_field_" place holder?
For context, our users submit large amounts of information within one ticket field. This will include bullets, spaces, indents and paragraphs. When our agents use the Macro to populate a comment using the Custom Field, it comes out in one block of text and makes it very challenging.
When using the Macro our agents want to mirror the formatting used when inputting text into the custom field to help them better work on the ticket.
Thanks!
Hi nrooney,
If I'm understanding you correctly, you may be able to set something up using liquid markup. I was able to track down a useful tip that may help point you in the right direction: How do I display multi-select field values as bullet points?
I hope this helps!
Hi!
I have configured custom userfield with keyfield "staff_id", in user profiles it is displayed and working.
I have tried many different ways to use it, but {{ticket.requester.custom_fields.staff_id}} returns nothing.
@Константин-Чернышков:
Did you mean that field "staff_id" to refer the current user (agent), or the ticket requester?
Because it's not possible to reference a custom user fields for the current user (agent) in macros or business rules, you can only reference custom user fields that refers to the ticket requester.
Of course, i mean ticket requester. End-user. His staff id i need to get and save in the ticket.
And I can't get value of ticket requester userfield. Variable I wrote above returns nothing.
Ok. In that case, {{ticket.requester.custom_fields.staff_id}} should work, as long as staff_id is the id of the user field on the current ticket requester.
Mind not all placeholders are supported in all locations. For example, "ticket" object is not available in agent signatures.
Also, you might want to try to reload your Zendesk to ensure any changes to your request user fields has been loaded. If I set a user field to a new value, and immediately use a placeholder in a comment that reference that field, sometimes I see that the new value is not registering until I refresh my browser session.
If nothing of the above works, can you tell where you are trying to use the placeholder - is it in a macro, a trigger, automation, dynamic content, etc?
How does one customise the text of a CC email so that it contains different information for an agent who's CC'd vs an end-user who's CC'd?
There's only a single CC email template (under Tickets / CCs / CC email text), so presumably the only way is to embed a condition within that template.
But I don't see any placeholder for the user to whom the email is being sent?
Hello Phil,
Sorry for the delayed response, but you can customize the text in email notifications to requesters and CCs by editing the Notify requester of the received request and notify the requester of comment update default triggers. You must be an administrator to customize default triggers.
To customize default triggers for email notifications to requesters and CCs
Best regards.
Hi Devan--
Thanks for the reply.
The issue is not customising the email that goes to the requester vs. a CC.
The issue is customising the email sent to "CC who is a support agent" vs. the email sent to "CC who is an end-user". I can see no way to do that.
Thanks,
-Phil
Hi Phil,
Actually CC contacts who are support agents will now be automatically set as Followers since the release of the Follower feature.
Therefore this means that you can no longer set a specific email template for CC notifications like we used to be able to do in the past.
Hope this clarifies.
I'm using ticket.description in the JSON body of a trigger action that goes to an HTTP target. I find that instead of simply including the request description, I get a bunch of extra formatting including a horizontal rule, date, and name of the person who left the comment. Is there some way to avoid this, and just get the text of the description?
"text": "----------------------------------------------\n\nFirst Last, Mar 24, 17:04\n\nNew Comment!"
Have the same issue as Kolbe. Any updates Devan - Community Manager?
I know we can pass the user.organization.id vis placeholder, has anyone found the place holder for the Organization External ID?
This would be useful especially when the external id's are referencing actual account numbers in a CRM.
Hi Jason,
There is a placeholder for the external organization id in the placeholders, ticket.organization.external_id. It's in the "ticket data" section of this article.
Hope that works for you!
Hi Kolbe
This looks like something where we would need specific examples to troubleshoot. We're creating a ticket for you so that this can be investigated more deeply.
Thank you Gail L - your comment is going to save lives.
Hi,
I literally copied #{{ticket.id}} from this article and inserted it into my trigger, but my customers still receive ticket ID as plain text, not a link to the ticket. What could it be?
Eugenia Pavlovskaya you can refer the article https://support.zendesk.com/hc/en-us/articles/203662156-Zendesk-placeholders-reference#topic_giz_opl_rc
{{ticket.link}} should be used to get ticket URL.
Thanks Dinesh! But {{ticket.link}} adds just full url, while I want the #ticket_number to be linked with this url. Basically the visual representation of simple HTML (<a href="ticket_link">ticket_id</a>), and #{{ticket.id}} is claimed to give this result but it doesn't - I still have lain text #25 in my notifications.
you can add this line. <a href="{{ticket.link}}">{{ticket.id}}</a>
this should work. You can use inline CSS.
Please sign in to leave a comment.