Prompting & Variables

Variables enable you to personalize agent prompts and messages with dynamic data. RevRing provides system variables automatically and supports custom variables that you can set through the API or webhooks.

Variable Types

RevRing supports three types of variables:

System Variables: Automatically provided for every call with contextual information
Default Variables: Static variables you configure on the agent that apply to all calls
Dynamic Variables: Call-specific variables set per outbound call or via pre-call webhook for inbound calls

Variables merge with the following priority: system variables are set first, then default variables are applied, and finally dynamic variables can override both system and default variables.

System Variables

System variables are automatically available in every call and provide contextual information about the call itself.

Variable	Description	Example
`{{direction}}`	Whether the call is inbound or outbound	`inbound` or `outbound`
`{{user_number}}`	The customer’s phone number	`+14155551234`
`{{agent_number}}`	Your agent’s phone number (caller ID for outbound)	`+12025559999`
`{{current_time}}`	Current timestamp when the call starts, formatted in the agent’s timezone	`Tuesday, November 26, 2025 at 2:30:00 PM EST`
`{{timezone}}`	The agent’s IANA timezone identifier	`America/New_York`
`{{language}}`	The agent’s language code	`en`

System variables are always available for you to use in your agent’s prompt and first message.

Example Usage

You are a customer service agent.

CALL INFORMATION:
- Call direction: {{direction}}
- Customer phone: {{user_number}}
- Our number: {{agent_number}}
- Current time: {{current_time}}

Greet the customer and provide assistance based on the {{direction}} call context.

Default Variables

Default variables are static values you configure on your agent that apply to every call. These are useful for consistent information like business name, hours, or policies.

Setting Default Variables

Configure default variables via the Update Agent API:

curl -X PATCH https://api.revring.ai/v1/agents/agent_123abc \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultVariables": {
      "business_name": "Acme Corp",
      "business_hours": "Monday-Friday 9am-5pm EST",
      "support_email": "support@acme.com"
    }
  }'

These variables will be available in your prompt as {{business_name}}, {{business_hours}}, and {{support_email}}.

Example Prompt with Default Variables

You are the receptionist for {{business_name}}.

INFORMATION:
- Business hours: {{business_hours}}
- Support email: {{support_email}}

Answer customer questions about our services and schedule appointments during business hours.

Dynamic Variables

Dynamic variables are set on a per-call basis and override default variables. The method for setting them differs between outbound and inbound calls.

For Outbound Calls

Set dynamic variables when sending an outbound call via the Send Call API:

curl -X POST https://api.revring.ai/v1/calls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123abc",
    "fromNumber": "+12025559999",
    "toNumber": "+14155551234",
    "variables": {
      "customer_name": "John Smith",
      "appointment_time": "2:00 PM today",
      "confirmation_code": "ABC123"
    }
  }'

For Inbound Calls

Set dynamic variables by returning them from your pre-call webhook. See the Webhooks guide for implementation details. Your webhook receives caller information and returns variables:

{
  "variables": {
    "customer_name": "Sarah Johnson",
    "account_status": "premium",
    "last_order_date": "March 10, 2024"
  }
}

Complete Example

Here’s a comprehensive example showing all variable types in action:

Agent Configuration

Default Variables (via API):

{
  "business_name": "Dr. Smith's Dental Office",
  "office_hours": "Monday-Friday 8am-6pm"
}

Prompt:

You are an appointment booking assistant for {{business_name}}.

CALL INFORMATION:
- Call direction: {{direction}}
- Customer phone: {{user_number}}
- Office phone: {{agent_number}}
- Current time: {{current_time}}

OFFICE DETAILS:
- Hours: {{office_hours}}

YOUR TASK:
Help {{customer_name}} schedule a dental appointment.

GREETING:
Start by greeting {{customer_name}} warmly and confirming you're speaking with them at {{user_number}}.

CONVERSATION FLOW:
1. Greet {{customer_name}} and mention you see they're calling from {{user_number}}
2. Ask what type of appointment they need (cleaning, checkup, emergency, etc.)
3. Check their preferred date and time
4. Confirm the appointment details including:
   - Patient name: {{customer_name}}
   - Callback number: {{user_number}}
   - Appointment date and time
   - Type of appointment
5. Let them know they'll receive a confirmation text at {{user_number}}

Keep responses concise and professional. The current time is {{current_time}}, so suggest appropriate appointment slots during {{office_hours}}.

First Message:

Hi {{customer_name}}, this is Alex from {{business_name}}. I see you're calling from {{user_number}}. How can I help you today?

Setting Dynamic Variables

For outbound calls:

curl -X POST https://api.revring.ai/v1/calls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_123abc",
    "fromNumber": "+12025559999",
    "toNumber": "+14155551234",
    "variables": {
      "customer_name": "John Smith"
    }
  }'

For inbound calls (pre-call webhook response):

{
  "variables": {
    "customer_name": "Sarah Johnson"
  }
}

Where Variables Are Substituted

{{variable}} placeholders are replaced in all of the following fields:

Agent prompt
First message
Voicemail message
Warm transfer fields: hold message, summary instructions (the briefing spoken to the person you transfer to), and intro message

Substitution uses the variables available on that specific call: system variables, the agent’s default variables, and the per-call variables you send. A placeholder whose variable is not set on the call is left exactly as typed (for example {{external_id}} stays visible), so missing data is easy to spot rather than silently disappearing. Make sure every variable referenced in these fields is supplied on each call.

First Message

The first message is the line your agent speaks when the call connects. It has two modes, controlled by the firstMessageMode field on the agent.

Static (default)

The agent speaks the firstMessage text exactly as written. It supports {{variables}}, just like the prompt:

Hi {{customer_name}}, this is Alex from {{business_name}}. How can I help you today?

Leave firstMessage empty to have the agent wait for the caller to speak first.

Dynamic

Set firstMessageMode to dynamic and the agent generates its opening line from the prompt instead of speaking a fixed string. This is useful when a single agent handles both inbound and outbound calls and needs a different greeting for each, since the {{direction}} system variable is available in the prompt:

You are a scheduling assistant for {{business_name}}.

When the call begins, greet the caller:
- If {{direction}} is inbound, thank them for calling {{business_name}} and ask how you can help.
- If {{direction}} is outbound, introduce yourself and explain you are calling to confirm their appointment.

Enable it via the API:

curl -X PATCH https://api.revring.ai/v1/agents/agent_123abc \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstMessageMode": "dynamic"
  }'

In dynamic mode the firstMessage text is ignored. To return to a fixed greeting, set firstMessageMode back to static (or null).

Working with Timezones

RevRing automatically handles timezone conversion for you. The {{current_time}} system variable is formatted in your agent’s configured timezone, and the {{timezone}} variable contains the IANA timezone identifier.

Setting Agent Timezone

Configure your agent’s timezone via the API when creating or updating an agent:

curl -X PATCH https://api.revring.ai/v1/agents/agent_123abc \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/New_York"
  }'

Or set it through the RevRing dashboard in your agent’s configuration.

Using Timezone in Prompts

Both {{current_time}} and {{timezone}} are automatically available as system variables:

You are an appointment scheduling assistant for {{business_name}}.

CURRENT TIME:
{{current_time}}

Your timezone is {{timezone}}. All times you communicate should be in this timezone.

When booking appointments:
1. Use the current time above as your reference
2. Suggest available slots in {{timezone}}
3. Always mention the timezone when confirming (e.g., "2 PM Eastern Time")

Timezone Format

Use IANA timezone identifiers (e.g., America/New_York, Europe/London, Asia/Tokyo) as they handle daylight saving time automatically. Common timezone identifiers:

US Eastern: America/New_York
US Central: America/Chicago
US Mountain: America/Denver
US Pacific: America/Los_Angeles
UK: Europe/London
Central Europe: Europe/Paris
India: Asia/Kolkata
Australia (Sydney): Australia/Sydney

Complete Example

You are scheduling appointments for {{business_name}}.

CURRENT TIME & TIMEZONE:
The current time is: {{current_time}}
Your timezone: {{timezone}}
Business hours: {{business_hours}}

INSTRUCTIONS:
1. Reference {{current_time}} when discussing availability
2. All appointment times should be stated in {{timezone}}
3. When confirming appointments, explicitly mention the timezone
4. If the customer mentions a different timezone, acknowledge it but confirm appointments in {{timezone}}

Example:
Agent: "I have availability tomorrow at 2 PM, 3:30 PM, and 5 PM Eastern Time. Which works best for you?"
Customer: "2 PM works"
Agent: "Perfect! I've scheduled you for 2 PM Eastern Time on [date]. You'll receive a confirmation."

Set your agent’s timezone to match your business location or primary customer base. For businesses serving multiple timezones, you can create separate agents for different regions, or override the system variables on a per-call basis when sending or receiving a call.

The {{current_time}} variable is formatted in a human-readable format like “Wednesday, November 26, 2025 at 8:30:00 PM EST” to make it easy for the AI to understand and communicate naturally.

Best Practices

Use descriptive variable names like customer_name instead of name to avoid confusion when debugging transcripts.

System variables like {{direction}} and {{current_time}} are particularly useful for context-aware prompts that behave differently for inbound vs outbound calls.

Dynamic variables override default variables. If you set a default variable and also pass it dynamically, the dynamic value will be used for that call.

Getting started

Platform

Variable Types

System Variables

Example Usage

Default Variables

Setting Default Variables

Example Prompt with Default Variables

Dynamic Variables

For Outbound Calls

For Inbound Calls

Complete Example

Agent Configuration

Setting Dynamic Variables

Where Variables Are Substituted

First Message

Static (default)

Dynamic

Working with Timezones

Setting Agent Timezone

Using Timezone in Prompts

Timezone Format

Complete Example

Best Practices

​Variable Types

​System Variables

​Example Usage

​Default Variables

​Setting Default Variables

​Example Prompt with Default Variables

​Dynamic Variables

​For Outbound Calls

​For Inbound Calls

​Complete Example

​Agent Configuration

​Setting Dynamic Variables

​Where Variables Are Substituted

​First Message

​Static (default)

​Dynamic

​Working with Timezones

​Setting Agent Timezone

​Using Timezone in Prompts

​Timezone Format

​Complete Example

​Best Practices

Variable Types

System Variables

Example Usage

Default Variables

Setting Default Variables

Example Prompt with Default Variables

Dynamic Variables

For Outbound Calls

For Inbound Calls

Complete Example

Agent Configuration

Setting Dynamic Variables

Where Variables Are Substituted

First Message

Static (default)

Dynamic

Working with Timezones

Setting Agent Timezone

Using Timezone in Prompts

Timezone Format

Complete Example

Best Practices