Zendesk messaging template variables: A complete guide for 2026

Zendesk messaging template variables are the key to personalizing customer conversations at scale. Whether you are pre-filling customer data, passing context between systems, or building dynamic AI agent responses, understanding how to use these variables effectively can transform your support operations.

This guide covers everything you need to know about Zendesk messaging template variables: what they are, how the syntax works, and practical ways to implement them in your support workflows.

What are Zendesk messaging template variables?

Template variables in Zendesk are placeholders that dynamically insert data into your messages. Think of them as labels that tell Zendesk: "Put the customer's name here" or "Insert the order number there."

These variables serve three main purposes:

• Personalization: Addressing customers by name, referencing their specific orders, or acknowledging their account history
• Automation: Passing data between your website, AI agents, and human agents without manual intervention
• Context preservation: Maintaining conversation details as customers move between bots and human support

There are three types of variables you will work with:

System variables come built into Zendesk. These include customer names, email addresses, ticket IDs, and other standard fields that Zendesk automatically tracks.

Custom variables are ones you create yourself. You might define a chosen_product variable to track what a customer selected, or a priority_level variable to indicate urgency.

Session variables are a newer addition that persist across conversation flows. Unlike step-specific variables, these follow the customer through multiple answers or dialogue branches in your AI agent.

At eesel AI, we approach variables with a similar philosophy: context should follow the customer naturally. Our AI teammates retain conversation history and customer data across interactions without complex configuration.

Understanding Zendesk messaging template variables syntax

Zendesk offers multiple syntax options depending on what you are trying to accomplish. Getting these right is crucial, as mixing them up is one of the most common mistakes we see.

Shorthand syntax for rich messages

Shorthand syntax lets you add buttons, images, and interactive elements to messages where rich formatting might not otherwise be available.

Here is how it works in practice. If you send a message with this text:

Thanks for reaching out! %[View order](https://shop.com/order/123) %[Talk to agent](reply:escalate)

Zendesk converts it into a message with two clickable buttons: one linking to the order page, and another that sends "escalate" as a reply payload.

Template insertion syntax

To insert a pre-defined template into a message, use this syntax:

%((template:template_name))%

There is also an alternative syntax in case the standard one conflicts with other templating systems:

%{{template:template_name}}%

If you include text alongside the template syntax, only the text before the template is sent as a separate message. Any text after the template syntax is ignored.

Variable interpolation

For variables you have defined in your AI agent flows, use double curly braces:

Hello {{customer_name}}, thanks for contacting us about order #{{order_id}}.

This syntax works for:

• Session variables that persist across answers
• Parameters captured from API calls
• Values collected in form fields

WhatsApp message templates

WhatsApp uses a different syntax with more parameters:

&((
  namespace=[[namespace]]
  template=[[template_name]]
  fallback=[[fallback_text]]
  language=[[language_code]]
  body_text=[[parameter_1]]
  body_text=[[parameter_2]]
))&

This syntax includes the namespace, template name, fallback text, language, and variable body text parameters.

Common syntax mistakes

The most frequent errors we see involve:

• Using single curly braces {variable} instead of double {{variable}}
• Forgetting the closing percent signs on template syntax
• Mixing up reply: and postback: button types
• Using spaces in template or variable names (use hyphens or underscores instead)

Using Zendesk messaging template variables in AI agents

Structured message templates are where variables really shine in Zendesk's AI agents. These templates let you create rich, interactive experiences without writing code.

Creating form templates

Form templates collect information from customers in a structured way. You can create them in AI agents - Advanced by navigating to Settings > CRM integration > Templates.

When creating a form template, you will configure:

Template name: This cannot contain spaces or special characters. Only hyphens and underscores are allowed. The name is what you will reference in your shorthand syntax.

Field types: Choose from email, text, or select (dropdown). All field labels are limited to 130 characters.

Variable names: Each field creates a variable with the name you specify. These variables become available in subsequent conversation steps.

Block messaging input: An optional setting that prevents customers from typing free text until they complete the form.

Best practice tip: Keep forms to five fields or fewer. Longer forms see significant drop-off rates, especially on mobile devices.

Creating custom JSON templates

For more complex interactions like carousels, lists, or NPS ratings, use custom JSON templates. These require some technical knowledge but offer greater flexibility.

The JSON structure follows Zendesk's structured message format. You can create carousels with multiple items, each containing an image, title, description, and action buttons.

Adding templates to conversation flows

Once you have created a template, you need to insert it into your AI agent dialogue:

1. Go to the Templates tab in your AI agent settings
2. Click the shorthand code to copy it to your clipboard
3. Open the dialogue where you want to use it
4. Paste the shorthand into an AI agent message block

The template renders automatically when the conversation reaches that step. If you have defined variables in the template (like form field names), those values are captured and can be used later in the flow.

Passing data with custom fields and metadata

One of the most powerful uses of Zendesk messaging template variables is passing data between your website, the messaging widget, and your support system.

Passing data to the Web Widget

You can pre-populate custom fields when a customer starts a conversation. This is useful for passing context like what page they are on, what product they are viewing, or their account status.

Here is the JavaScript implementation:

zE("messenger:set", "conversationFields", [
  { id: "7662882404114", value: "Blade Runner" }
])

The ID is your custom field ID from Admin Center. You can find this by going to Admin Center > Objects and rules > Tickets > Fields.

Critical requirement: The custom field must be set to end-user editable. If this setting is disabled, the data will not pass through.

When this code runs, the data is stored in the conversation metadata with this format:

{
  "metadata": {
    "zen:ticket_field:7662882404114": "Blade Runner"
  }
}

Retrieving metadata in AI agents

To use this data in your AI agent flows, you need to create an Action:

1. In your AI Agents Advanced dashboard, go to Content > Actions
2. Create a new Action with target "Sunshine Conversation"
3. Select the "Get conversation metadata" task
4. Retrieve the Metadata object and save it as a parameter

For the Key field, use the full metadata key: zen:ticket_field:7662882404114 (replace the ID with your actual field ID).

Once the action runs, you can access the value in your replies using {{parameter_name}} syntax.

Handling missing values

Always account for cases where the metadata might not be present. Add a conditional step that checks if your parameter has a value, then branch accordingly: show the pre-filled data if it exists, or ask the customer for input if it does not.

Updating metadata upon escalation

You can also send data back to Zendesk when escalating to a human agent. Create an "Update conversation metadata" action with:

• Key: zen:ticket_field:YOUR_FIELD_ID
• Value: {{your_variable}}

Add this action to your Escalation block. When the conversation transfers to an agent, the ticket field is automatically populated with the variable value.

Important limitations:

• System fields like subject and status cannot be updated via Sunshine Conversations metadata
• For dropdown fields, you must pass the associated tag value, not the display text
• For lookup fields, pass the ID of the custom object, user, or organization

Practical implementation examples

Let us walk through some real-world scenarios where Zendesk messaging template variables make a difference.

Example 1: Pre-filling customer context from web page

An e-commerce company wants to pass the product a customer is viewing into the support conversation.

Setup:

1. Create a custom text field "Product Viewing" in Zendesk
2. Add this JavaScript to the product page:

   zE("messenger:set", "conversationFields", [
     { id: "123456789", value: "Wireless Headphones X1" }
   ])
   

3. In your AI agent, create an action to get the metadata
4. In your greeting message: "I see you are looking at {{product_viewing}}. Do you have questions about this item?"

Example 2: Dynamic product recommendations via API

A retail company wants to show personalized product recommendations based on purchase history.

Setup:

1. Create an API call step that fetches recommendations using the customer ID
2. Store the returned array as a variable (e.g., recommendations)
3. Use a Present Carousel step with dynamic configuration
4. Map carousel fields: Title = recommendation.name, Image = recommendation.image_url
5. Each carousel item links to the product page

Example 3: Form submission to ticket field workflow

A software company wants to collect deployment information before escalating to technical support.

Setup:

1. Create a form template with fields: Environment (select), Version (text), Issue Type (select)
2. Add the form to your escalation flow
3. Create variables from each field: deployment_env, software_version, issue_type
4. Before escalating, update conversation metadata for each field
5. When the ticket is created, these fields are pre-populated for the agent

Example 4: Session variables across conversation flows

A travel company wants to remember a customer's destination across multiple answers.

Setup:

1. In the "Book a trip" answer, use Present Options to collect destination
2. Store selection in {{chosen_destination}}
3. Use "Link to another answer" to send customer to "Hotel recommendations"
4. In the Hotels answer, reference {{chosen_destination}} to show relevant options
5. Later, link to "Activity recommendations" which also uses the same variable

This approach avoids asking the customer for their destination multiple times.

A simpler approach to template variables with eesel AI

If you are finding Zendesk's variable system complex, you are not alone. The multiple syntax types, metadata requirements, and field permissions create a steep learning curve.

At eesel AI, we have taken a different approach to context and variables. Our AI teammates learn your business from day one by connecting to your existing systems: help centers, past tickets, macros, and documentation. Context flows naturally through conversations without manual configuration.

Here is how we handle what Zendesk does with template variables:

No-code variable passing: Instead of writing JavaScript to pass data to the widget, eesel AI integrates directly with your e-commerce platform, CRM, or help desk. Customer data, order history, and account details are automatically available to the AI.

Automatic context retention: Session variables happen automatically. If a customer mentions they are using a mobile device in their first message, that context persists through the entire conversation without you creating variables or setting up actions.

Plain English instructions: Rather than learning shorthand syntax, you simply tell eesel AI what to do: "If the refund request is over 30 days, politely decline and offer store credit." No code, no syntax, no complex flows.

Progressive rollout: Start with eesel AI drafting replies for your agents to review. As you see it understands your business, expand to full autonomous resolution. You control the pace based on actual performance.

For teams already using Zendesk, eesel AI integrates directly with your help desk. The AI can access your existing macros, help center articles, and ticket history, making the transition seamless.

Best practices and getting started

If you are implementing Zendesk messaging template variables, here are recommendations based on what we have seen work:

Naming conventions

• Use descriptive names: customer_email is better than field1
• Stick to lowercase with underscores: order_number not OrderNumber
• Avoid Zendesk reserved words: do not use ticket, user, or organization as variable names
• Keep it short: you will be typing these often in message blocks

Testing before going live

Always test your variable flows thoroughly:

• Test with missing values to ensure conditional logic works
• Test across different channels (web widget, mobile SDK, WhatsApp)
• Test the escalation path to verify ticket fields populate correctly
• Use Zendesk's conversation preview to spot-check before publishing

Security considerations

• Never pass sensitive data (credit card numbers, passwords) through conversation metadata
• Review which fields are end-user editable; disable editing for sensitive fields
• Use API tokens with minimal required permissions for integrations
• Regularly audit your custom fields and actions

Performance tips

• Minimize API calls; cache data when possible
• Use session variables instead of repeated API calls for data that does not change
• Keep form templates short to reduce abandonment
• Test variable-heavy flows on mobile devices to ensure responsive performance

Next steps

Start simple. Pick one use case, like greeting customers by name or pre-filling a single custom field. Get comfortable with the basic syntax before building complex multi-variable workflows.

Once you have mastered the fundamentals, explore Zendesk's documentation on advanced template features like message overrides for Apple Messages for Business or WhatsApp-specific formatting.