Zendesk Support placeholders reference

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:

• Understanding placeholder suppression rules
• Using placeholders

User data

In the context of updating a ticket, there are a number of different types of users. These include the following:

• 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).

Table 1. User object data

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: Advisor Light Agent Staff Team Leader Legacy Agent Administrator 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.

Note: The behavior of the first name and last name placeholders depends on the formatting of the name on the profile. For example, if you use the name Dutch van der Linde, the placeholder user.last_name will show 'Linde'. If you use the name van der Linde, Dutch on the profile, then the placeholder user.last_name will show 'van der Linde'.

Organization data

Each type of user can be added to an organization. An organization contains the following data properties.

Table 2. Organization data object

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.

Since all users can be added to an organization, you can access the organization data for each using Liquid markup. For example, you can return data for each of the these types of users (shown here as placeholders):

• {{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.

Table 3. Agent data object

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.

Table 4. Ticket object data

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: {% for cc in ticket.ccs %} {{cc.name}} ({{cc.email}}) {% endfor %}
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

Comments are added to tickets, so they can be accessed as a ticket data object. There are three types of ticket objects:

• 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.

Table 5. Standard comment data

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: comment.author.name comment.created_at comment.created_at_with_time comment.is_public (true for public comments and false for private comments) comment.value comment.value_rich comment.id comment.attachments attachment.filename attachment.url 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. 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.

Table 6. Formatted comment data

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.

Table 7. Rich text comment data

Properties/placeholders	Description
ticket.latest_comment_rich	The most recent comment. Rich text formatting. Does not include attachments - to include 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)

The following data properties are available for customer satisfaction rating (see Using customer satisfaction ratings).

Note: If you suspect that satisfaction scores are being left by users other than the requester, you might be using satisfaction rating placeholders outside of business rules. Do so enables others users to submit satisfaction scores for the requester (see Satisfaction rating submitted by non-requester).

Table 8. Satisfaction rating data object

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.