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 %}
69 comments
Scott Davis
currently,
{{ticket.url}} does not render as a clickable URL in email notifications. is there a way to do this?
0
Beto
Hi there Scott!
This happens sometimes because the {{ticket.url}} placeholder does not include "http://" or "https://" as you can see on our Placeholder Reference article. This might affect if the url is clickable.
The easiest solution is to use the {{ticket.link}} placeholder, which does include this, or add the missing section yourself, like this:
http://{{ticket.url}}
https://{{ticket.url}}
I hope this helps!
1
Andy M
I've tried every variation of trying to get anything in the organization to come back and its always blank
{{custom_fields.custom_cust_id}}},
{{ticket.organization.name}}
{{ticket.requester.organization.name}}
{{ticket.requester.organization.external_id}}
{{ticket.requester.org..custom_cust_id}}
{{ticket.requester.organization.custom_fields..custom_cust_id}}
{{ticket.requester.organization.custom_cust_id}}
0
Dave Dyson
Hi Andy,
Where are you attempting to use these? I created a macro in my test account that adds a comment including these two placeholders:
{{ticket.organization.name}}
{{ticket.requester.organization.name}}
If the ticket requester has an associated Organization, the placeholders resolve and display the organization name. I also added these placeholders to the notification text box in my "Notify requesters and CCs of comment update" trigger, and they worked there as well. I think your custom field placeholders above should also work, so long as you're substituting the field ID into the placeholder as instructed in the documentation above.
If you're still not able to get these to work, I'd suggest chatting with our support team (Option 1 here: Contacting Zendesk Customer Support), so they can help you troubleshoot.
0
Conor Quarry
Hi,
Is it possible to create custom Zendesk Placeholders within our Macros, which can then be updated through the API? I'm noticing no API call I make, despite success, changes the field value within, ie, I want to add {{iban}} and {{phone_number}}.
0
Karyn Close
I'm not able to get this placeholder to work in a macro. I've tried substituting the key name for the ID as well and neither work. The Org Custom field (text) is correct and has data. The Org is also associated with the requester. Logically, it should work but does not.
{{ticket.organization.custom_fields.<key_name>}}
0
Arkadiusz Szafraniec
Hi Everyone!
Does {{ticket.ticket_field_<field ID number>}} works with a text field?
I've tried on macro and it didn't work. Value in a comment is always blank.
0
Diogo Maciel
I encourage you to create a new post in the General Product Feedback topic in our community to engage with other users who have similar needs and discuss possible workarounds. Conversations with a high level of engagement ultimately get flagged for product managers to review when they go through roadmap planning.
Specific examples, details about impact, and how you currently handle things are helpful for our product teams to understand the full scope of the need when working on solutions. You may also want to review the Product feedback guidelines and how to write an effective feedback post [https://support.zendesk.com/hc/en-us/community/posts/360004391547-Product-feedback-guidelines-how-to-write-a-good-feedback-post].
We truly value customer feedback and your voice and votes in the forums help influence future Zendesk functionality.
0
Arkadiusz Szafraniec
Hi Diogo,
thank you for the answer. To be clear, text fields doesn't work only for macros? Did they work for automatic notifications via triggers and automations?
0
Diogo Maciel
https://support.zendesk.com/hc/en-us/articles/4408843597850-Contacting-Zendesk-Customer-Support
0
Jose Mª
Hi,
I am using a drop-down control.
When using the placeholder: ticket.ticket_field_option_title_id, I see that I am getting the display value and not the internal label value.
How can I get the internal label, or is it not possible?
Regards
0
Diogo Maciel
https://support.zendesk.com/hc/en-us/articles/4408843597850-Contacting-Zendesk-Customer-Support
0
Jose Mª
Hi Diogo,
I am referring to the values and the tags of the field values:
1: is the value the customer sees
2: is the tag, the internal value of the field value
Regards.
0
Diogo Maciel
Ah I see, thank you for clarifying. Yes, unfortunately placeholders will only display the value of the field and not the associated tag. The tag present in dropdown fields' values serve mainly to have a referenceable value internally for things like searches, viewsa and reports. I am sorry for the inconvenience.
0
Jose Mª
Thanks, Diogo!
0
Sydney Neubauer
Is there a placeholder for the current users custom field? There is "ticket.requester.custom_fields.<key_name>" but this pulls in the requester's custom field and not the current User making the comment.
0
Sabra
Hey Sydney! You can use the following placeholder format to pull the current user custom user field information:
For drop-down custom user fields, you'll want to use this format:
2
mccabe.tonna
the checkbox logic should actually be swapped.
should actually be
reason: when a checkbox is not visible on a form; it returns null value. This accounts for explicitly checked boxes
1
Dave Dyson
0
Konstantin
@Administrador and @...,
It is possible to list the "tag" value (natively) for drop-down options, by utilizing " ticket.ticket_field_id ". To clarify, for drop-down options, this is the behavior:
This is not true for all Field types, but it is possible for single-select drop-down fields.
~Konstantin
4
Marc Iacobino
Hello, what is the correct format for the "phone" placeholder? For example, for as French number such as ... (+33) 12 45 78 78
0
Joyce
Are you looking for the placeholder to use to pull the phone number value on the ticket requester's user field? If so, you can use the placeholder {{ticket.requester.phone}},
which pulls the ticket requester's phone number on file. Check our Zendesk Support placeholders reference for more information.
If it is about the acceptable phone number format that you are inquiring about, phone numbers should be formatted with the internationally standardized E.164 format. E.164 numbers can have a maximum of fifteen digits and are usually written as follows: [+][country code][subscriber number including area code].
1
Rudolph
Shoutout to Konstantin for that perfect solution! Exactly what I needed. That info should be added to the article, Anton de Young / @...
1
Jeff Killian
Hi Joyce,
I am trying to use a custom user field in a macro but the format is coming back reading:
2022-01-15 00:00:00 +0000
The data in the customer profile shows "January 15, 2022" which matches the format I want to use in my Macro. Can you help me solve this please?
0
Dane
If you can share to use the placeholder that you are using, maybe we can determine what could be causing this behavior.
0
Amit Chinchane
Is there any place holder like {{user_email}} which can display the user email id on the help center page.
For example:
This show the full name of the user who is logged in on the help centre
0
Mike DR
I see you have an open ticket for this, will reach out to you there!
0
Chin Sin
Hi, is it possible to use the place holder in the request body of the webhook?
Background:
I am using webhook to trigger an update to the ticket to populate a custom ticket field with the requester's external_id.
API Request Body
{
"ticket": {
"custom_fields": [
{
"id": 8706713219609,
"value": "{{ticket.requester.id}}"
}
]
}
}
Result
The ticket field will be updated with the text {{ticket.requester.id}} instead of the value.
If I did not include the opening and closing quotes, I get the following error.
{
"error": "Unprocessable Entity",
"message": "Server could not parse JSON"
}
0
Tipene Hughes
Hi Chin Sin,
Placeholders cannot be used to populate custom ticket fields, unfortunately. In addition, we advise against using triggers and webhooks to update tickets using the API as this can potentially lead to race conditions which may result in unexpected behavior. Here’s an article which goes in to more detail:
https://support.zendesk.com/hc/en-us/articles/4408882855578-Can-I-use-a-trigger-and-a-webhook-to-update-tickets-
One possible way you could achieve the same result is using a background ZAF app that makes a PUT request to the tickets API in response to an event. You can find out more about the apps framework here:
https://developer.zendesk.com/documentation/apps/app-developer-guide/using-the-apps-framework/
I hope this helps! Feel free to reach out with any questions.
Tipene
Edit: See following comment for clarification around testing custom fields and placeholders
0
Chin Sin
Hi Tipene Hughes,
It seems that the test webhook does not work for placeholder but the placeholder works with the actual trigger + webhook.
The solution was actually proposed by Zendesk technical consultant due to the limitation that no custom field or tags can be included in the tickets created via messaging.
For the race conditions, we are only using it when ticket is created and if the custom field is empty.
Thank you.
CS
0