Placeholders are references to ticket, user, and custom data that you include in the subject and body of email notifications. Without them it would be impossible to create automated messages. When you specify placeholders, remember they are case sensitive. For the complete list of placeholders see Zendesk Support placeholders reference.
Support includes system ticket rules that suppress placeholders in ticket triggers in certain situations. System ticket rules are predefined rules that you cannot change, modify, or override, which dictate the standard behavior of Support. These rules may sometimes make it seem like placeholders in ticket 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. See Understanding placeholder suppression rules.
Related articles:
Using placeholders in business rules
Placeholders can be used in some, but not all, business rule actions. When placeholders are supported, a View available placeholders button is visible beneath the field. Placeholders are formatted within matched double curly brackets. Usually they are used in notification messages and reference ticket properties. If a placeholder references a field that doesn't have a value, the placeholder is blank in the automation, trigger, or macro.
Here’s an example of how placeholders are used in an email notification:
For the complete list of placeholders, and where they can be used, see Zendesk Support placeholders reference. If you want more control on how placeholder data is selected and displayed, see Understanding Liquid markup.
Using placeholders in macros
When you apply a macro containing a placeholder to a ticket, the placeholder is evaluated according to what is currently true about the ticket. If the output of the evaluation returns any information, it is added as a ticket comment. For example, if a macro that returns the ticket ID is run on a ticket that has not been saved (and therefore has no ticket number yet), the ticket comments aren't updated. The macro is not re-evaluated when the ticket is saved. You could manually add the placeholder to the ticket using the placeholder {{ticket.id}}. This would allow it to be evaluated when you submit the ticket, and the value returned by the placeholder would be added to the ticket comments.
When using macros with problem and incident
tickets, you often need use a backward slash
(\) to escape the placeholder so that it populates the
appropriate value within the related incident tickets. For
example: Hello
\{{ticket.requester.first_name}}
Using placeholders for custom fields
Placeholders are generated automatically, based on the ticket, current user, and custom object properties. These are referred to as system placeholders.
When you add custom fields for tickets, users, organizations, and custom objects, they are also available as placeholders. You can use placeholders for your custom fields as you would any other system placeholder. Every custom field has a unique ID or key. When you create a custom ticket field, the ID is automatically generated for you. When you create a custom user, custom org, or custom object field, you enter a unique key that cannot be edited once it is set.
Custom fields are not included in the list of available placeholders, but all custom fields except drop-downs follow this simple naming pattern that references their unique ID or key.
Ticket custom fields | {{ticket.ticket_field_<field ID number>}} |
User custom fields | {{ticket.requester.custom_fields.<field_key>}} |
Organization custom fields | {{ticket.organization.custom_fields.<field_key>}} |
Custom object fields | {{custom_object.<object_key>.custom_fields.<field_key>}} |
For example, a custom ticket field like this has the following placeholder:
{{ticket.ticket_field_505156}}
To find the ID for a custom ticket field
-
In Admin Center, click
Objects and rules in the sidebar, then select Tickets > Fields.
Locate your field in the list. The ID is displayed in the Field ID column.
To find the key for a custom user field or a custom organization field
- Open the configuration for User fields or
Organization fields.
- In Admin Center, click
People in the sidebar, then select Configuration > User fields.
- In Admin Center, click
People in the sidebar, then select Configuration > Organization fields.
- In Admin Center, click
- Click the name of a custom field.
The field key appears in the properties panel on the right.
To find the key for a custom object field
- In Admin Center, click
Objects and rules in the sidebar, then select Custom objects > Objects.
- Click the name of the object.
- Click the Fields tab.
- Find the field in the list and look at the value displayed in the Field key column.
Using placeholders for a custom drop-down field
The placeholder name for the options in a custom drop-down list follows a different pattern. There's only one placeholder for all four drop-down list options because this is a reference to the option that was selected. The ID is for the custom drop-down list because options do not have IDs. Again, this is a reference to the single option that was selected.
Ticket custom drop-down fields Ticket custom multi-select fields |
|
User custom drop-down fields | {{ticket.requester.custom_fields.<field_key>.title}} |
Organization custom drop-down fields | {{ticket.organization.custom_fields.<field_key>.title}} |
Custom object drop-down fields | {{custom_object.<object_key>.custom_fields.<field_key>.title}} |
For example, the placeholder for a drop-down list for a custom ticket field would look like this:
{{ticket.ticket_field_option_title_515416}}
Using placeholders for a custom lookup relationship field
Lookup relationship fields are a type of custom field that is used to define relationships between objects. They are supported for all of the standard Zendesk objects (tickets, users, and organizations) and custom objects.
In addition to using placeholders to surface data related to the primary object, such as a ticket requester's name, you can also use placeholders to surface data in related records. For example, if you have a ticket with a lookup relationship field that points to a user, you could use placeholders to reference data about that user. Similarly, you could use a placeholder to reference ticket data through a custom object's lookup relationship field and vice versa. For the purposes of these placeholders, the standard ticket requester and organization fields are treated as lookup relationship fields.
To reference data in related records, use the lookup relationship field's field key. This will follow the pattern for custom fields. See examples.
You can also use placeholders supported for the target object in a lookup relationship field. For example, a lookup relationship field that points to users can leverage the user data placeholders.
Placeholders referencing data through a ticket lookup relationship field can be used in ticket triggers and macros. Placeholders referencing data through custom object lookup relationship fields can be used in object triggers.
Examples of using placeholders to retrieve data from related records
Working with the ticket Requester field
For example, the Requester field in a ticket is functionally a lookup relationship field pointing to a user. If you've defined a user lookup relationship field with a field key of manager that points to another user, then you could use the following placeholder to display the asset requester's manager's name:
ticket.requester.custom_fields.manager
You could also take it one step further because you're working with the ticket requester field, and create a side conversation email to the ticket requester's manager using the following placeholder:
ticket.requester.custom_fields.manager.email
This is great for approval workflows, where you might need to notify the manager or get the manager's sign-off.
Working with custom organization lookup relationship fields
The Organization field is another standard ticket field that is functionally a lookup relationship field pointing to an organization. You could use organization lookup relationship fields to associate an organization with a custom object named contract. Then you could leverage the ticket's organization field to retrieve data from the contract record associated with the organization, which itself (the organization) is associated with the ticket, and use the following placeholder to communicate the contract's end date:
{{ticket.organization.custom_fields.contract.custom_fields.end_date}}
Both the requester and organization ticket fields are special cases because they are standard ticket fields that function as lookup relationship fields. Therefore, you can go two "hops" deep with the lookup relationship field placeholders to retrieve data from a record related to the record related to the primary object. In the example above, the ticket is the primary object, the ticket's organization is the first "hop", and the contract record related to the organization is the second "hop."
When dealing with custom lookup relationship fields, you can go only one "hop" deep into the record directly related to the primary object.
Working with custom lookup relationship fields
An example of working with custom lookup relationship fields might be a ticket lookup relationship field with a field key of 2698798899085 that points to a custom object named Order. The order object has a custom drop-down field with the field key order_status. To reference the status of the order record that's associated with the ticket, use the following placeholder:
{{ticket.ticket_field_2698798899085.custom_fields.order_status.title}}
When working with drop-down fields, you must include
.title
in the placeholder to
return the selected value.
Using placeholders for a custom checkbox field
You can use placeholders in combination with Liquid markup to verify if a checkbox (custom field) has been selected on a ticket and provide customized output based on the checkbox status (selected or not selected).
When you use Liquid markup if/else/case
statements for checkbox custom ticket fields, remember that
the checkbox field has a value of 0 or 1, not
false or true. For example:
{% if ticket.ticket_field_<insert field_id here> contains 1 %}
checkbox is checked
{% else %}
checkbox is unchecked (or null)
{% endif %}
70 comments
Tipene Hughes
Hi Chin Sin,
I've done a bit more testing on my end and you are correct, the placeholder does populate to the custom fields when using triggers + webhooks. As you noted, it does not populate as expected when testing using something like Postman. The reason for this is that when the webhook fires, it runs through a proxy which populates the placeholder field with the actual value before being sent to the specified endpoint. This does not occur when using Postman hence you see the placeholder sent as a string.
Sorry for any confusion but I hope this clears it up. Feel free to reach out with any questions!
Tipene
0
Colleen Hall
Hi Konstantin,
Thank you for providing this solution! And thank you Rudolph for pointing it out. I've updated the article with this information.
1
Rudolph
Wooo, thanks for doing that, Colleen Hall!
0
Joubin Saedi
the checkbox logic should actually be swapped.
should actually be
Screen Value: {{% if ticket.ticket_field_9508015623188 contains 1 %}}
Screen Value line, from above, does not work for getting if the checkbox was selected.
0
Albert Lechuga
Hello, do placeholder work in the Email HTML template. For example, If I add an HTML signature and I use {{current_user.phone}} where the phone number would go, should it display the agent that responded to the ticket's phone number in the HTML signature? I have been unable to get any {{current_user.XXX}} placeholders to show anything in the HTML template.
0
Gab Guinto
I'm afraid the system placeholders like current_user.phone won't work when used within email templates. An alternate solution is to use the signature field in the user profiles; you can use these placeholders within that field. But, at this time, the signature field does not support HTML. You may only use Markdown formatting.
If you can, I suggest that you upvote or add a comment to this product feedback thread - Feature Request: HTML or Rich Text Editor for Signatures.
Thanks Albert!
0
Maddie F.
Hi! Can this article please be edited to mention that placeholders are case-sensitive? I found this out today while working with a Zendesk agent to troubleshoot an issue I was encountering and I think it may be helpful to include it on this page.
0
Lisa Kelly
I updated both these Placeholder articles to include the following sentence:
"When you specify placeholders, remember they are case-sensitive."
https://support.zendesk.com/hc/en-us/articles/4408886858138
https://support.zendesk.com/hc/en-us/articles/4408887218330
I'm marking this ticket as Solved. Let me know if you disagree.
0
Ke Zhao
Hi. I am trying to apply macro with placeholder {{ticket.requester.first_name}} when I create ticket via Zendesk API, but the placeholder won't be replaced in this situation. The placeholder only works when I update a ticket via API. Just wonder how to create a ticket with placeholder in comment via API? Thanks.
0
Konstantin
Ke Zhao,
Out of curiosity, are you running all of this in one command? If so, it won't work (from similar testing and work I've performed), as Zendesk doesn't understand who the Requester is until the ticket is actually saved with the Requester's details. It is best to perform this within two steps (first create the ticket, then have automation apply the Macro).
~Konstantin
0
Ke Zhao
Thank you for your quick reply, Mike Konstantin. I am running
GET /api/v2/macros/{macro_id}/apply
to get the comment from macro first, then call
POST /api/v2/tickets
Yes, I think you are right, Zendesk won't understand the requester. I had a workaround to create a ticket with a starting comment, then update the ticket with macro. Thank you!
0
Luke Aleo
I used a placeholder {{ticket.ticket_field_option_title_<field ID number>}} to show content from a Multi-Select Dropdown. The ticket itself looks fine, but when I search for it the results are showing the {{ticket.ticket_field_option_title_<field ID number>}} instead of the actual data. Is this a user error on my part or working as intended?
0
Dane
I have tried the placeholder below and it worked on my end. Make sure to use Cmd/Ctrl + Shift + V when pasting to avoid converting it to HTML.
0
Leticia
I'm creating a placeholder for the chat in Zendresk. I need a placeholder that automatically modifies the brand of the casino we are serving, as well as the name of customers and agents changing when adding the placeholder. Is that possible?

0
Viktor Osetrov
Unfortunately, it doesn't work for the web widget (Classic) chat trigger.
However, it works for web widget Messaging. I have tested the following scenario.
1. Created placeholder using dynamics content for each brand
2. Added my custom placeholder "" into triggers and macros.
Please notice content text is different for each language.
It works for both cases.
Hope it helps
0
Shaun Murray
I am trying to use a custom number field as a placeholder for another number field. It fails validation and won't let me save the trigger because placeholders aren't numbers. Is there any workaround for this?
0
Viktor Osetrov
Did you try to use regular expressions as a ticket field for your digits validation? For example, this is RegEX for checking digit numbers from 1 to 9:
[0-9]{9}(,[0-9]{9})*,?
This is an example from this article.
Hope it helps
0
Chad Susa (Gravity CX - Zendesk Partner)
Hi @...
In your post above, did you confirm if a Text field value can be referenced in a macro using a placeholder - {{ticket.ticket_field_<field_id>}}? You mentioned that you tested this and it worked in your agent workspace...can you explain how you got this working?
Many thanks
Chad
0
Konstantin
Chad Susa (Gravity CX - Zendesk Partner),
That placeholder works for all Custom Fields, no matter what type of Field they are. The main take-away about placeholders, if you use this for Drop-Down Fields, you will get their Tag identifier versus their "label"; For the "label" (i.e. user-friendly value), you will want to use ticket.ticket_field_option_title_<field ID>. One other note when using the "label" placeholder option, if you have nested (i.e. drop-out) values in your Field options, you will see the value displayed as such:
Example
Field is called "Support", with the following options:
This is how you would see your placeholder values, when they are populated. Just in case, placeholders can be used in:
I hope this information helps. If there is something more specific, please provide your Use Case and I will try to help answer your question/s the best I can.
~Konstantin
0
Chad Susa (Gravity CX - Zendesk Partner)
Thanks Konstantin
I must be doing something wrong. I can't seem to get a placeholder working for a text field in a macro. I'm sure I'm going crazy.
I have made a small video here to show you what I mean: Zendesk Placeholders in Macros
0
Carmelo Rigatuso
Is there any way to display the text contained in the dropdown field, instead of the tag? Replying to customers with something like "Thank you for selecting super_awesome_prem..." looks really ugly. Would much rather display "Thank you for selecting Super Awesome Product, Premium Edition ...".
thanks,
Cmr
0
Shaun Murray
Hi Chin,
{{ticket.ticket_field_option_title_<field ID number>}} is the placeholder you will want for those.
1
Hannah Lucid
Hi! Is there a way to pull CC email addresses into a Macro? We want to send this information when we use Ticket Sharing since it doesn't pull over this information in the Shared Instance's ticket.
0
Tyler Williams
Hi there, I'm trying to use this in a Macro that adds an internal note but I'm running into some issues.

Based on the instructions, it appears that I should be using {{ticket.organization.custom_fields.72024.title}} this however returns as blank. The ticket has an Organization with a value in this custom field. That field applied the relevant tag to the ticket. Am I missing something with this?
0
Joyce
If you want to return the email addresses of the people CC'd on the message in a macro, you can use this Liquid code:
You can also visit this article for more information: Ticket data placeholder
Hello Tyler,
You have the correct placeholder, which is
{{ticket.organization.custom_fields.<field_key>.title}}
, but instead of using the custom field ID72024
, you need the field keyplatform
.2
Tyler Williams
Hi Joyce,
I'm not sure how I missed that in all this. Thank you for pointing out my mistake. Thats working perfectly now. Have a great day.
0
Jose Mª
Hello,
in reference to this question I asked a while ago:
https://support.zendesk.com/hc/en-us/articles/4408887218330/comments/4412492584986
is it still not possible to select the value of the label, instead of the one seen by the client?
I am using it to call a service and the label is a more stable value. If you can't, I think it would be a useful thing to develop in the future.
Thanks
0
Shawna James
0
Elizabeth
Hi,
I have a dropdown with diffrent level of sub item, How can I get the last item in the dropdown with the placeholder?
0
Paolo
You can use the
{{ticket.ticket_field_option_title_<field ID number>}}
for your use case. You can find more information here.Best,
Paolo | Technical Support Engineer | Zendesk
0