English (US)
  1. Zendesk help
  2. Objects and rules
  3. Objects and rules documentation
  4. Business rules

Using placeholders

Anton de Young
  • Edited

What's my plan?

Suite allall plans

Placeholders are references to ticket and user 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 seeZendesk Support placeholders reference.

Support includessystem ticket rulesthat suppress placeholders in 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 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. SeeUnderstanding placeholder suppression rules.

This article includes these sections:

Related articles:

Using placeholders in business rules

The placeholders are contained within matched double curly brackets and are, in the following example, references to ticket properties. If a placeholder references a field that does not have a value, then the placeholder will be blank in the automation, trigger, or macro.

Here’s an example of how placeholders are used in an email notification:

When you’re composing email notifications, you can view the list of placeholders by clickingView Available Placeholders.

For the complete list of placeholders, and where they can be used, seeZendesk Support placeholders reference. If you want more control on how placeholder data is selected and displayed, seeUnderstanding Liquid markup.

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 will not be 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.

Using placeholders for custom fields

Placeholders are generated automatically, based on the ticket and current user properties. These are referred to as system placeholders.

When you add custom fields for tickets, users, or organizations, 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 or custom org 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 they follow this simple naming pattern that references their unique ID or key.

Ticket custom fields {{ticket.ticket_field_}}
User custom fields {{ticket.requester.custom_fields.}}
Organization custom fields {{ticket.organization.custom_fields.}}

For example, a custom ticket field like this has the following placeholder:

{{ticket.ticket_field_505156}}

The placeholder name for the options in a custom drop-down list follows a different pattern. There's only one placeholder for all three 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

 {{ticket.ticket_field_option_title_}}

{{ticket.ticket_field_}}

Note:The {{ticket.ticket_field_option_title_}} placeholder displays the title of the selected options while {{ticket.ticket_field_}} displays the tags associated with the selected options.
User custom drop-down fields {{ticket.requester.custom_fields..title}}
Organization custom drop-down fields {{ticket.organization.custom_fields..title}}
Note:Take note of the syntax, as the placement of标题in the placeholder varies, depending on the type of custom field.

For example, the placeholder for a drop-down list for a custom ticket field would look like this:

{{ticket.ticket_field_option_title_515416}}

To find the ID for a custom ticket field

  • InAdmin Center, clickObjects and rulesin the sidebar, then selectTickets > Fields.

    Locate your field in the list. The ID is displayed in theField IDcolumn.

To find the key for a custom user field or a custom organization field

  1. Open the configuration forUser fieldsorOrganization fields.
    • InAdmin Center, clickPeoplein the sidebar, then selectConfiguration > User fields.
    • InAdmin Center, clickPeoplein the sidebar, then selectConfiguration > Organization fields.
  2. Click the name of a custom field.

    The field key appears in the properties panel on the right.

Using placeholders for a checkbox custom field

You can use placeholders in combination with液体的标记to verify if a checkbox (custom field) has been selected on a ticket and provide customized output based on the checkbox status (checked, or not checked).

When you use Liquid markupif/else/casestatements for checkbox custom ticket fields, remember that the checkbox field has a value of0or1, notfalseortrue. For example:

{% if ticket.ticket_field_ contains 1 %} checkbox is checked {% else %} checkbox is unchecked (or null) {% endif %}
    Return to top

    56 Comments

    • Tipene Hughes
      Zendesk Developer Advocacy

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

      但是我抱歉的混乱hope this clears it up. Feel free to reach out with any questions!

      Tipene

      0
    • Colleen Hall
      • Edited
      Zendesk Documentation Team

      HiKonstantin,

      Thank you for providing thissolution! And thank youRudolph Beatonfor pointing it out. I've updated the article with this information.

      1
    • Rudolph Beaton

      Wooo, thanks for doing that,Colleen Hall!

      0
    • Joubin Saedi

      the checkbox logic should actually be swapped.

      {% if ticket.ticket_field_contains 0 %} checkbox is unchecked {% else %} checkbox is checked {% endif %}

      should actually be

      {% if ticket.ticket_field_contains 1 %} checkbox is checked {% else %} checkbox is unchecked (or null) {% endif %}



      Can someone give me an example of what the checkbox line will actually look like when you enter it into a the trigger section?

      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
      Zendesk Customer Care
      Hi Albert,

      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 theseplaceholderswithin that field. But, at this time, the signature field does not support HTML. You may only useMarkdown 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.

      嗨！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
      Zendesk Documentation Team
      Thanks, Maddie,
      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

      嗨。我试图用占位符{{应用宏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_}} 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_}} instead of the actual data. Is this a user error on my part or working as intended?

      0
    • Dane
      Zendesk Engineering
      Hi Luke,

      I have tried the placeholder below and it worked on my end. Make sure to useCmd/Ctrl + Shift + Vwhen pasting to avoid converting it to HTML.
      {{ticket.ticket_field_option_title_6613023110543}}

      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
      Zendesk Customer Care
      Hello Leticia,

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

      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
      Zendesk Customer Care
      HelloShaun,

      Did you try to useregular expressionsas 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 thisarticle.

      Hope it helps
      0
    • Chad Susa (Gravity CX - Zendesk Partner)

      HiDiogo Maciel

      Inyour post above, did you confirm if a Text field value can be referenced in a macro using a placeholder - {{ticket.ticket_field_}}? 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 useticket.ticket_field_option_title_. 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:

      • Access::Can't Login
      • Access::Portal Unavailable
      • Device::Not Powering On
      • Device::Replacement
      • ...etc

      This is how you would see your placeholder values, when they are populated. Just in case, placeholders can be used in:

      • Automation policies
      • Trigger policies
      • Macros
      • 入站和出站API调用(通过人)

      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)

      ThanksKonstantin

      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_}} is the placeholder you will want for those.

      1
    • Hannah Lucid

      嗨！有办法把抄送邮件地址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
      Zendesk Customer Care
      Hello Hannah,

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

      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..title}}, but instead of using the custom field ID72024, you need the field keyplatform.


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

    Pleasesign into leave a comment.

    Related articles

    Powered by Zendesk