Skip to content

dynamic-variables.mdx

Latest commit

 

History

History
168 lines (125 loc) · 6.23 KB

dynamic-variables.mdx

File metadata and controls

168 lines (125 loc) · 6.23 KB
title Variables
subtitle Personalize assistant messages with dynamic and default variables
slug assistants/dynamic-variables

Overview

Use dynamic variables in the system prompt or any message in the dashboard with double curly braces (e.g., {{name}}).

To set values, make a phone call request through the API and set assistantOverrides. You cannot set variable values directly in the dashboard.

For example, set the assistant's first message to "Hello, {{name}}!" and assign name to John by passing assistantOverrides with variableValues:

{
  "variableValues": {
    "name": "John"
  }
}

Using dynamic variables in a phone call

Create a JSON payload with these key-value pairs:

  • assistantId: Replace "your-assistant-id" with your assistant's actual ID.
  • assistantOverride: Customize your assistant's behavior.
    • variableValues: Include dynamic variables in the format { "variableName": "variableValue" }. Example: { "name": "John" }.
  • customer: Represent the call recipient.
    • number: Replace "+1xxxxxxxxxx" with the recipient's phone number (E.164 format).
  • phoneNumberId: Replace "your-phone-id" with your registered phone number's ID. Find it on the Phone number page.

Send the JSON payload to the /call/phone endpoint using your preferred method (e.g., HTTP POST request).

{
  "assistantId": "your-assistant-id",
  "assistantOverrides": {
    "variableValues": {
      "name": "John"
    }
  },
  "customer": {
    "number": "+1xxxxxxxxxx"
  },
  "phoneNumberId": "your-phone-id"
}
Ensure `{{variableName}}` is included in all prompts where needed.

Default Variables

These variables are automatically filled based on the current (UTC) time, so you don't need to set them manually in variableValues:

Variable Description Example
{{now}} Current date and time (UTC) Jan 1, 2024 12:00 PM
{{date}} Current date (UTC) Jan 1, 2024
{{time}} Current time (UTC) 12:00 PM
{{month}} Current month (UTC) January
{{day}} Current day of month (UTC) 1
{{year}} Current year (UTC) 2024
{{customer.number}} Customer's phone number +1xxxxxxxxxx
{{customer.X}} Any other customer property
{{transport.conversationType}} Whether the conversation is over chat or voice chat
{{transport.X}} Any other transport-related property

Advanced date and time usage

You can use advanced date and time formatting in any prompt or message that supports dynamic variables in the dashboard or API. We use LiquidJS for formatting - see their docs for details.

Format a date or time using the LiquidJS date filter:

{{"now" | date: "%A, %B %d, %Y, %I:%M %p", "America/Los_Angeles"}}

Outputs: Monday, January 01, 2024, 03:45 PM

Examples:

  • 24-hour time: 
    {{"now" | date: "%H:%M", "Europe/London"}}
    → 17:30
  • Day of week: 
    {{"now" | date: "%A"}}
    → Tuesday
  • With customer number: 
    Hello, your number is {{customer.number}} and the time is {{"now" | date: "%I:%M %p", "America/New_York"}}

Common formats:

Format String Output Description
%Y-%m-%d 2024-01-01 Year-Month-Day
%I:%M %p 03:45 PM Hour:Minute AM/PM
%H:%M 15:45 24-hour time
%A Monday Day of week
%b %d, %Y Jan 01, 2024 Abbrev. Month Day

Using dynamic variables in the dashboard

To use dynamic variables in the dashboard, include them in your prompts or messages using double curly braces. For example:

Hello, {{name}}!

When you start a call, you must provide a value for each variable (like name) in the call configuration or via the API/SDK.

Always use double curly braces (`{{variableName}}`) to reference dynamic variables in your prompts and messages.

Setting assistant prompt using conversation type

Using the transport.conversationType variable in your assistant's system prompt, you can modify how it behaves in chats or calls:

[Identity]
You are a helpful assistant, talking with a customer via {{transport.conversationType}}.

[Response Guidelines]
{% if transport.conversationType == "chat" -%}
- Format numbers naturally; eg, a US phone number could be +1 (555) 123-4567
- Use Markdown formatting for lists (both unordered and ordered)
{%- elsif transport.conversationType == "voice" -%}
- Always spell numbers in words; eg, 256 should be 'two hundred and fifty six'
- Only ask one question at a time
- Never use Markdown format; write everything as if it is being said aloud
{%- endif -%}

HIPAA and Zero Data Retention mode

When HIPAA mode or Zero Data Retention is enabled for your organization or assistant, Vapi does not store any call data, including variable values. This means:

  • Variable values passed via variableValues are processed during the call but not persisted after the call ends
  • Call logs, recordings, and transcriptions are not stored
  • Variables are only available in real-time during the active call session

This ensures compliance with privacy requirements while still allowing you to personalize conversations with dynamic variables.

For more information on enabling HIPAA compliance and understanding data retention policies, see the [HIPAA Compliance](/security-and-privacy/hipaa) documentation.