Zendesk Support placeholders reference Follow

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.

This article categorizes the placeholders by the data they display:

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 that you need to replace user with one of the user types shown above this table (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). Administrator users return as agent.
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.

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 that you need to replace user with one of the user types shown below this table (for example, ticket.requester).
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 added to public ticket comments and outgoing messages. 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 signature, 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 The names of the people cc'd on the message.

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.created_at Date the ticket was created (for example, May18, 2014).
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).
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.group.name The group assigned to the ticket.
ticket.id The ticket ID.
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.url Ticket URL.
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. 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. See Adding custom fields to users.
ticket.score Score.    
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. 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.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 two types of ticket objects. The first allows you to also return a collection of comment and attachment data. The second type is preformatted and these placeholders simply return comments in predefined formats.

Table 5. Comment data object
Properties/placeholders Description
ticket.comments Used as a placeholder, {{ticket.comments}} displays all the comments in a ticket (both public and private) in unformatted text. Although private comments are always filtered out of the notifications that are sent to the requester.

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.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 (both public and private). Unformatted text. Does not include attachments. To return attachments, use ticket.latest_comment_formatted.
ticket.latest_public_comment The most recent public comment. Unformatted text.
Table 6. Formatted comment data
Properties/placeholders Description
ticket.comments_formatted All public and private comments, most recent first.
Note: Private comments are filtered out of notifications that are sent to end-users.
ticket.public_comments_formatted All public comments, most recent first.
ticket.latest_comment_formatted The most recent comment (both public and private) with attachments (if any).
ticket.latest_public_comment_formatted The most recent public comment.

Satisfaction rating data (Professional and Enterprise)

The following data properties are available for customer satisfaction rating (seeUsing customer satisfaction ratings (Professional and Enterprise).).
Table 7. 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.
Have more questions? Submit a request

Comments

  • 1

    Hi Anton,

    The placeholder {{ticket.id}} creates a link in the emails sent to the requester. Is it possible to insert the ticket id without it forming a link.

    I don't want my customers to use the web portal.

    Thanks

    Andy. 

  • 0

    I'll answer my own question...

    Just found another article by Anton about setting up an email only help desk.

    https://support.zendesk.com/entries/20032793-setting-up-an-email-only-help-desk

  • 0

    I'm using a custom loop for my email template but am having a problem with comment formatting.  It seems that when I loop {% for comment in ticket.comments %}, comment.value isn't formatted.  But when I loop {% for comment in ticket.public_comments_formatted %}, comment is actually the comment value, not a comment object, so I can't access other comment details (like attachments).  Do I have to loop ticket.comments to get access to the comment details?  If so, is there something like comment.formatted_value that I can access on each comment object?  What I'm picturing is:

    {% for comment in ticket.public_comments_formatted %}

    {{comment.formatted_value}}

    Attachments:

    {% for attachment in comment.attachments %}

    {{attachment.url}}

    {% endfor %}

    {% endfor %}

    Thanks!

  • 0

    Looks like ticket.tags is a simple space separated string rather than something you can iterate over directly (so you can't do

    {% for tag in ticket.tags %} Tag: {{ tag }}{% endfor %}

    For searching, you can use

    {% capture spacetags %} {{ ticket.tags }} {% endcapture %}{% if spacetags contains " mytag " %} tagstuff {%endif %}

  • 0

    I would like the subject line of the "comment added" notification to include the name of the commenter. Currently I'm trying this:

    [Comment] {{comment.author.name}} Re: {{ticket.title}}

    As the subject line, but nothing is coming through for the comment author name. Any suggestions? 

  • 0

    Hi, I'm using the Triggers to a URL endpoint to do so some ticket updates for my system. This trigger will send info about the ticket to the URL endpoint.The message contains ticket.updated_at and  ticket.created_at fields.

    I'm not sure what timezone the dates are taking. The user I'm using in the target is configured in UTC. Could you please clarify?ticket.updated_at and  ticket.created_at  fields don't have any time or timezone info.

  • 0

    Tawney,

    Remember that {{comment.author.name}} is part of the ticket.comments data collection so you can't (that I know of) refer to it separately. 

    Try this in your subject line: 

    [Comment] {% for comment in ticket.comments limit:1 offset:0 %}{{comment.author.name}}{% endfor %} RE: {{ticket.title}}

    That returns the author of the last (most recent) comment. 

  • 0

    Sangeetha, 

    The ticket_updated_at and ticket_created_at placeholders use your account's time zone. 

  • 0

    I created custom fields. How do I reference them in a macro? i.e. one is:

    Control Panel Username

     

     

  • 0

    Found it: {{ticket.ticket_field_ID}} The value of a ticket custom field. For example, {{ticket.ticket_field_123}}.

     

  • 0

    Is it possible to have the placeholder {{ticket.title}} without the (ticket #1111) at the end?!

    I just need to have the Ticket Title within the subject.

    Thanks,

    Bojan 

  • 0

    Bojan,

    The {{ticket.title}} placeholder only returns the ticket's subject - not the ticket number. You're getting the ticket number as well? Where are you using the placeholder? 

  • 0

    In my case it does it. I'm using the default placeholder within the trigger:

    • Notify requester of received request
    • Notify requester of comment update

    Any idea?!

  • 0

    Bojan, 

    I just tested it in those triggers and I'm not getting the ticket number. I'll open a support request for you and one of our support agents will look into this for you. 

  • 0

    Great, Thank you Anton.

    Maybe it has something to do with our account. It was in use beginning 2011, then closed, and now re-activated again.

  • 0

    Just for your information or BTW: I'm talking here about the Emails which are produced by those triggers.

  • 0

    Hi Bojan,

    If you're using a non-zendesk email address for a default reply address, we add the ticket title into the subject line.  We need to do this in order for the ticket replies to thread properly.  (When you use a mycompany.zendesk.com email address, we put this information in a token in your reply address, but that's unavailable to us when you use your own address.)  Sorry for any confusion that this causes. If you have further questions, please feel free to reach out to us at support@zendesk.com.

  • 0

    Hi Joy,

    Thank you. That make sense. But, is it somehow possible to adjust the wording:

    For example from (ticket #1111) to just Ticket #1111

  • 0

    Cornelia Böhm

    {{ticket.ticket_field_option_title_ID}} instead of{{ticket.ticket_field_ID}}

  • 0

    I'm using an URL target to deliver ticket information and emulating JSON structures.  This breaks when a user uses characters like apostrophe or quotes.  Are there any sort of functions like urlquote available?

  • 0

    Any idea when the ticket URL placeholder will support the new agent interface? Currently clicking on the URL in an email reverts you back to the Classic design.

     

    It would be nice if it would automatically detect that you are an agent and keep you in the new interface without having to change the URL itself as that would cause problems when a client clicks on it.

  • 0

    Hi,

    I just worked on some Macros on this one and noted that some important information is not in the objects:

    • Age in hours of the ticket
    • Time since last update

    These would be great to have to generate more custom responses.

     

    Thanks,

    Christian

  • 0

    We want to show the ticket description, but truncated to a max length. This is in a HipChat URL target.

    This:

    {{ticket.description | truncate:400}}

    Is truncated correctly, but the description is always prefixed with something like "------ Sender Name, The Date" as Deepak Sapra described above.

    If we do:

    {{ticket.latest_comment | truncate:400}}

    We don't get the prefix, but neither is it truncated.

    If we use ticket.latest_comment_formatted, it has the prefix and is truncated fine, exactly like ticket.description.

    Is this by design or a bug? Is there some way to get a truncated ticket description without that prefix, but with truncation?

  • 0

    Hi,

    In the web interface for a ticket, in the events and notifications area, it shows all the change events for a ticket, e.g.:

    • Group changed from Support to -
    • Group changed from - to Service Management
    • Group set to Support
    • Status set to New

     

    We need this in emails, as currently it is very hard to know what has happened from the current email template. Is there anyway to isolate and email exactly what has changed, as is possible to see on the web?

  • 0

    I notice that ticket.created_at and updated_at just have the date. Are there any fields that give me the time as well? I'm trying to set up some if statements so that on holidays they get a specialized message. I can set it for just the date right now, but I'd like my specialized message to begin at 5PM the day before so that people submitting know their ticket won't be answered until we return after the holiday. If there's a better way to do that, I'm up for that too!

  • 0

    Hi,

    I need a placeholder that shows the date/time stamp of a ticket, in the format: dd.mm.yyyy hh:mm:ss (e.g. 02.12.2012 15:01:10). When I use for instance {{ticket.created_at}} , I get DEC 02 for instance, which is not what I need.

    Moreover, can I adjust the output of the date/time stamp? I would like to be yyyy.mm.dd for instance.

    Thanks in advance,

    Richard

  • 0

    Time stamp would be a great addition.  Coupled with this, it would be FANTASTIC if we could refer to this in triggers and rules.  Rather than having to use 'hours' all the time (though these work great, just looking at options)

  • 0

    Is there a way to insert the linked ticket ids? For example, my ticket is of type problem and I want to show in the comments (private) what the linked incident ticket numbers are. This is so an external system (JIRA) will get the information (since I don't have another easy way of showing this). 

    Thanks :)

  • 0

    I'd like to have a widget [app?] visible at login that displays the current number of unsolved tickets and the total number of tickets solved [since the beginning or maybe even for a certain timeframe] Are there placeholders for these two pieces of data? Or maybe an app for this already exists?

  • 0

    Thanks for the feedback, folks! I'd like to see a timestamp specific placeholder as well. Just as a reminder, ticket notifications should all include a timestamp, it's just not tied to a placeholder. 

    David: This sounds doable with a bit of custom coding, though I wouldn't know where to start. Maybe somebody else has some input? To my knowledge, no application exists which displays that information. 

    Annastashia: You'll have to drop that information in manually, or populate some custom fields with the relavent ticket details. You could then use a custom placeholder to share that data: https://support.zendesk.com/entries/20011631-using-placeholders#topic_nfp_nja_vb

Powered by Zendesk