Dynamic Variables & Templating - Oration AI Documentation

Overview

Oration enables dynamic content in agent prompts and conversations. Create personalized, context-aware interactions by injecting variables, applying filters, and using conditional logic directly in your agent prompts. Use double curly braces {{ }} for variables and {% %} for logic tags to create data-driven prompts that adapt to each conversation.

Key Benefits

Dynamic Personalization: Insert customer names, account details, and contextual information
Conditional Logic: Show different content based on customer data or conversation state
Data Formatting: Apply filters to format dates, numbers, and text automatically
Reusable Templates: Create flexible prompts that work across different scenarios

Using Dynamic Variables in Conversations

Basic Variable Injection

Inject dynamic variables into your agent prompts:

Hello {{name}}, welcome to {{companyName}}! 

I see you're calling about your account {{account.id}}. 
How can I help you today?

Conditional Content

Use conditional logic to personalize responses based on customer data:

{% if customer.isPremium %}
As a premium member, I can offer you priority support and exclusive options.
{% else %}
I'd be happy to help you today. Did you know we offer premium support for faster service?
{% endif %}

{% if customer.lastPurchaseDate %}
I see your last purchase was on {{customer.lastPurchaseDate | date: "%B %d, %Y"}}.
{% endif %}

Working with Nested Variables

Oration supports complex nested data structures in variables. You can access nested properties using dot notation and work with arrays and objects seamlessly.

Accessing Nested Properties

<!-- Access nested object properties -->
{{customer.profile.firstName}}
{{customer.address.street}}
{{order.items.first.name}}

<!-- Access array elements by index -->
{{customer.orders[0].total}}
{{customer.phoneNumbers[1]}}

Working with Objects

<!-- Customer profile object -->
Customer: {{customer.profile.firstName}} {{customer.profile.lastName}}
Email: {{customer.profile.contact.email}}
Address: {{customer.profile.address.street}}, {{customer.profile.address.city}}

<!-- Account details -->
Account Type: {{account.settings.type | capitalize}}
Preferences: {{account.settings.preferences.notifications}}

Working with Arrays

<!-- Loop through arrays -->
Your recent orders:
{% for order in customer.orders %}
  - Order #{{order.id}}: {{order.total | currency}} on {{order.date | date: "%B %d, %Y"}}
{% endfor %}

<!-- Access array properties -->
Total orders: {{customer.orders.size}}
Latest order: {{customer.orders.first.total | currency}}
{% if customer.orders.size > 0 %}
Most recent purchase was {{customer.orders.first.date | date: "%B %d"}}.
{% endif %}

<!-- Convert arrays to natural language sentences -->
{% assign productNames = products | map: "name" %}
Available products: {{productNames | array_to_sentence_string}}
<!-- Output: "Product A, Product B, and Product C" -->

{% assign customerInterests = customer.interests %}
I see you're interested in {{customerInterests | array_to_sentence_string}}.
<!-- Output: "I see you're interested in technology, sports, and music." -->

<!-- Convert arrays with custom conjunctions -->
{{customer.phoneNumbers | array_to_sentence_string: "or"}}
<!-- Output: "555-1234, 555-5678, or 555-9999" -->

<!-- Handle different array sizes naturally -->
{% if customer.preferences.size == 1 %}
Your preference is {{customer.preferences.first}}.
{% else %}
Your preferences are {{customer.preferences | array_to_sentence_string}}.
{% endif %}

Complex Nested Structures

<!-- Multi-level nesting -->
{{organization.departments.sales.manager.name}}
{{user.preferences.notifications.email.frequency}}

<!-- Nested conditionals -->
{% if customer.subscription.plan.features.premiumSupport %}
  You have access to our premium support team.
  Support hours: {{customer.subscription.plan.supportHours.start}} - {{customer.subscription.plan.supportHours.end}}
{% endif %}

<!-- Nested arrays and objects -->
{% for contact in customer.emergencyContacts %}
  Emergency Contact: {{contact.name}} ({{contact.relationship}})
  Phone: {{contact.phone | default: "Not provided"}}
{% endfor %}

Use conditional checks to avoid errors when nested properties might not exist:

<!-- Safe access with conditional checks -->
{% if customer.profile %}
  Name: {{customer.profile.firstName | default: "Not provided"}}
{% endif %}

{% if customer.orders.size > 0 %}
  Last order: {{customer.orders.first.total | currency}}
{% else %}
  No previous orders found.
{% endif %}

<!-- Using default filters for safe access -->
{{customer.profile.firstName | default: "Valued Customer"}}
{{customer.address.city | default: "your area"}}

Default Variables

Oration provides several built-in system variables that are always available in your prompts:

System Variables

Variable	Description	Example
`language`	Current conversation language	`"en-US"`
`currentTime`	Full current date and time	`"Monday, August 27, 2024 at 12:25:37 PM IST"`
`currentDate`	Current date only	`"Monday, August 27, 2024"`

Usage Examples

Today is {{currentDate}} and the current time is {{currentTime}}.

{% if language == "en-US" %}
I'll be speaking with you in English today.
{% elsif language == "es-ES" %}
Hablaré contigo en español hoy.
{% endif %}

Custom Dynamic Variables

Define custom variables that are evaluated at runtime:

<!-- These would be defined in your agent configuration -->
Welcome to {{company.name}}! 
Your account balance is {{customer.balance | currency}}.
The weather today is {{weather.current | capitalize}}.

Data Formatting Filters

Filters transform variable output using the pipe | operator. Most useful filters for agent prompts:

Text Formatting

<!-- Capitalize first letter -->
{{customer.name | capitalize}}

<!-- Convert to uppercase -->
{{product.code | upcase}}

<!-- Convert to lowercase -->
{{customer.email | downcase}}

<!-- Remove extra whitespace -->
{{customer.notes | strip}}

<!-- Truncate long text -->
{{description | truncate: 100}}

<!-- Replace text -->
{{phone | replace: "-", " "}}

Date and Time Formatting

<!-- Format dates -->
{{order.date | date: "%B %d, %Y"}}          <!-- August 27, 2024 -->
{{order.date | date: "%m/%d/%Y"}}           <!-- 08/27/2024 -->
{{order.date | date: "%A, %B %d"}}          <!-- Monday, August 27 -->

<!-- Relative time -->
{{order.date | date: "%-d days ago"}}

Number Formatting

<!-- Format as currency -->
{{price | currency}}                        <!-- $29.99 -->
{{price | currency: "EUR"}}                 <!-- €29.99 -->

<!-- Round numbers -->
{{rating | round: 1}}                       <!-- 4.7 -->

<!-- Add commas to large numbers -->
{{revenue | number_with_delimiter}}         <!-- 1,234,567 -->

Conditional and Logic Filters

<!-- Default values -->
{{customer.name | default: "Valued Customer"}}

<!-- Check if empty -->
{% unless customer.email == blank %}
I'll send a confirmation to {{customer.email}}.
{% endunless %}

<!-- Map values -->
{% assign statusText = order.status | map: "pending" => "Processing", "shipped" => "On the way" %}

Advanced Filter Combinations

<!-- Chain multiple filters -->
{{customer.name | strip | capitalize | default: "Guest"}}

<!-- Format complex data -->
Your account ({{account.id | upcase}}) has a balance of {{account.balance | currency}} 
as of {{account.lastUpdated | date: "%B %d at %I:%M %p"}}.

<!-- Conditional formatting -->
{% assign urgency = ticket.priority | downcase %}
This is a {% if urgency == "high" %}🔴 HIGH PRIORITY{% elsif urgency == "medium" %}🟡 MEDIUM PRIORITY{% else %}🟢 STANDARD{% endif %} request.

Essential Liquid JS Keywords & Syntax

Understanding these key Liquid JS keywords will help you create more powerful and flexible agent prompts. These are the most commonly used control structures and operators.

Control Flow Keywords

Conditionals

<!-- if/elsif/else -->
{% if customer.status == "premium" %}
  Premium customer benefits apply.
{% elsif customer.status == "standard" %}
  Standard customer service available.
{% else %}
  Basic support provided.
{% endif %}

<!-- unless (opposite of if) -->
{% unless customer.email == blank %}
  I'll send you a confirmation email at {{customer.email}}.
{% endunless %}

<!-- case/when for multiple conditions -->
{% case customer.priority %}
  {% when "high" %}
    🔴 High priority support
  {% when "medium" %}
    🟡 Medium priority support
  {% when "low" %}
    🟢 Standard support
  {% else %}
    Regular customer service
{% endcase %}

Loops and Iteration

<!-- for loop -->
{% for order in customer.orders %}
  Order {{forloop.index}}: {{order.total | currency}}
{% endfor %}

<!-- for loop with conditions -->
{% for item in cart.items %}
  {% if item.onSale %}
    🏷️ SALE: {{item.name}} - {{item.price | currency}}
  {% endif %}
{% endfor %}

<!-- for loop with else (when array is empty) -->
{% for order in customer.orders %}
  {{order.id}}: {{order.total | currency}}
{% else %}
  No orders found.
{% endfor %}

Variable Assignment and Manipulation

<!-- assign - create variables -->
{% assign fullName = customer.firstName | append: " " | append: customer.lastName %}
{% assign discountRate = 0.15 %}
{% assign isEligible = customer.years >= 2 %}

<!-- capture - capture block content as variable -->
{% capture greeting %}
  Hello {{customer.name}}, welcome to {{company.name}}!
{% endcapture %}

<!-- increment/decrement -->
{% assign counter = 0 %}
{% increment counter %}  <!-- counter is now 1 -->
{% decrement counter %}  <!-- counter is now 0 -->

Comparison and Logic Operators

<!-- Equality operators -->
{% if status == "active" %}Active account{% endif %}
{% if status != "inactive" %}Account is working{% endif %}

<!-- Comparison operators -->
{% if customer.age >= 18 %}Adult customer{% endif %}
{% if order.total < 100 %}Small order{% endif %}
{% if balance > 0 %}Positive balance{% endif %}
{% if items <= 5 %}Few items{% endif %}

<!-- Logical operators -->
{% if customer.isPremium and customer.balance > 0 %}
  Premium customer with positive balance
{% endif %}

{% if customer.email == blank or customer.phone == blank %}
  Missing contact information
{% endif %}

<!-- Contains operator -->
{% if customer.interests contains "technology" %}
  Tech-savvy customer detected
{% endif %}

Special Keywords and Properties

<!-- Loop properties (available in for loops) -->
{% for item in items %}
  {% if forloop.first %}First item: {% endif %}
  {% if forloop.last %}Last item: {% endif %}
  {{item.name}} ({{forloop.index}} of {{forloop.length}})
{% endfor %}

<!-- Size property -->
{% if customer.orders.size > 5 %}
  Frequent customer with {{customer.orders.size}} orders
{% endif %}

<!-- Empty/blank checks -->
{% if customer.notes != empty %}
  Notes: {{customer.notes}}
{% endif %}

{% if customer.email != blank %}
  Email on file: {{customer.email}}
{% endif %}

<!-- Array access -->
{{customer.orders.first.date}}  <!-- First element -->
{{customer.orders.last.total}}   <!-- Last element -->
{{customer.phoneNumbers[0]}}     <!-- By index -->

Flow Control Keywords

<!-- break - exit loop early -->
{% for order in customer.orders %}
  {% if order.status == "cancelled" %}
    {% break %}
  {% endif %}
  Processing order {{order.id}}
{% endfor %}

<!-- continue - skip to next iteration -->
{% for item in cart.items %}
  {% if item.outOfStock %}
    {% continue %}
  {% endif %}
  Available: {{item.name}}
{% endfor %}

Comments and Documentation

<!-- Single line comment -->
{%- comment -%}
  Multi-line comment
  This won't appear in output
{%- endcomment -%}

<!-- Liquid whitespace control -->
{%- if customer.name -%}    <!-- Remove whitespace before -->
  Hello {{customer.name}}!
{%- endif -%}               <!-- Remove whitespace after -->

Advanced Keywords

<!-- tablerow - create table rows -->
{% tablerow product in products cols:3 %}
  {{product.name}}: {{product.price | currency}}
{% endtablerow %}

<!-- raw - output liquid code without processing -->
{% raw %}
  {{customer.name}} will not be processed
{% endraw %}

<!-- include/render (if partials are supported) -->
{% render 'customer-info', customer: customer %}

Best Practices with Keywords

<!-- Use meaningful variable names -->
{% assign customerGreeting = "Hello " | append: customer.name %}

<!-- Combine keywords effectively -->
{% if customer.orders.size > 0 %}
  {% assign latestOrder = customer.orders.first %}
  {% if latestOrder.status == "delivered" %}
    Your recent order ({{latestOrder.id}}) was delivered {{latestOrder.deliveredDate | date: "%B %d"}}.
  {% endif %}
{% else %}
  This appears to be your first order with us!
{% endif %}

<!-- Use case statements for cleaner multiple conditions -->
{% case customer.subscription.type %}
  {% when "basic" %}
    Basic plan features available
  {% when "premium" %}
    Premium features unlocked
  {% when "enterprise" %}
    Full enterprise access
{% endcase %}

Best Practices

Always Provide Fallbacks

<!-- Good: Provides fallback -->
Hello {{customer.name | default: "there"}}!

<!-- Bad: Could result in empty output -->
Hello {{customer.name}}!

Use Meaningful Variable Names

<!-- Good: Clear and descriptive -->
{{customer.preferredName | default: customer.firstName}}

<!-- Bad: Unclear abbreviations -->
{{cust.pref | default: cust.fn}}

Format Data Consistently

<!-- Consistent date formatting -->
Account created: {{account.createdDate | date: "%B %d, %Y"}}
Last login: {{account.lastLogin | date: "%B %d, %Y"}}

<!-- Consistent currency formatting -->
Current balance: {{account.balance | currency}}
Credit limit: {{account.creditLimit | currency}}

Keep Logic Simple

<!-- Good: Simple and readable -->
{% if customer.isPremium %}
You have premium support access.
{% endif %}

<!-- Avoid: Overly complex nested logic -->
{% if customer.type == "premium" and customer.status == "active" and customer.balance > 0 %}
<!-- Complex nested conditions -->
{% endif %}

Common Use Cases

Customer Service Agent

Hello {{customer.firstName | default: "there"}}! I'm {{agent.name}}, your support specialist.

{% if customer.supportHistory.size > 0 %}
I can see we've helped you {{customer.supportHistory.size}} time{% if customer.supportHistory.size > 1 %}s{% endif %} before. 
Your last interaction was about {{customer.supportHistory.first.subject}}.
{% endif %}

What can I help you with today?

Sales Agent

Hi {{lead.name}}! Thanks for your interest in {{product.name}}.

{% if lead.budget %}
I see you mentioned a budget of {{lead.budget | currency}}. 
{% endif %}

{% if lead.company %}
I'd love to learn more about how {{product.name}} could help {{lead.company}} 
{% if lead.industry %}in the {{lead.industry}} industry{% endif %}.
{% endif %}

What specific challenges are you looking to solve?

Appointment Scheduling

{% assign nextSlot = availableSlots.first %}
{% if nextSlot %}
I have availability {{nextSlot.date | date: "%A, %B %d"}} at {{nextSlot.time | date: "%I:%M %p"}}.
{% else %}
I don't have any immediate availability, but I can check next week.
{% endif %}

{% if customer.timezone %}
All times are in {{customer.timezone}} timezone.
{% endif %}

Technical Reference

Oration’s dynamic templating is powered by LiquidJS, a robust templating engine that provides the syntax and filters described in this guide. For advanced use cases and additional filters not covered here, you can refer to the LiquidJS documentation for complete technical details and extended functionality.

Need more help? Reach out to our team at support@oration.ai

​Overview

​Key Benefits

​Using Dynamic Variables in Conversations

​Basic Variable Injection

​Conditional Content

​Working with Nested Variables

​Accessing Nested Properties

​Working with Objects

​Working with Arrays

​Complex Nested Structures

​Safe Navigation

​Default Variables

​System Variables

​Usage Examples

​Custom Dynamic Variables

​Data Formatting Filters

​Text Formatting

​Date and Time Formatting

​Number Formatting

​Conditional and Logic Filters

​Advanced Filter Combinations

​Essential Liquid JS Keywords & Syntax

​Control Flow Keywords

​Conditionals

​Loops and Iteration

​Variable Assignment and Manipulation

​Comparison and Logic Operators

​Special Keywords and Properties

​Flow Control Keywords

​Comments and Documentation

​Advanced Keywords

​Best Practices with Keywords

​Best Practices

​Always Provide Fallbacks

​Use Meaningful Variable Names

​Format Data Consistently

​Keep Logic Simple

​Common Use Cases

​Customer Service Agent

​Sales Agent

​Appointment Scheduling

​Technical Reference