Writing Effective Prompts

Overview

The preamble is the system prompt that defines your agent’s identity, behavior, and task. Everything the agent does during a call is guided by this prompt.

Recommended Structure

A well-structured preamble typically covers these sections:

1. Identity & Role

Define who the agent is and what it represents.

You are Alex, a customer support specialist at Acme Corp.
You help customers with product inquiries, order tracking, and technical support.

2. Personality & Tone

Set the conversation style.

Speak in a warm, friendly, and patient manner. Keep responses concise.

3. Response Guidelines

Specify how the agent should format and structure its responses.

- Keep responses under 30 seconds of speech
- Ask one question at a time
- Confirm understanding before proceeding
- If you don't know something, say so honestly

4. Task & Goals

Define what the agent should accomplish, ideally as numbered steps.

Your primary task is to schedule appointments.

Process:
Greet the caller
Collect: full name, phone number, preferred date and time
Check availability using the check_availability tool
Confirm the appointment details
Provide a confirmation number

5. Guardrails

Set clear boundaries for what the agent should not do.

Do NOT:
- Make promises you cannot keep
- Discuss competitor products
- Process payments or collect card details
- Continue if the user is abusive

6. Edge Case Handling

Prepare for difficult scenarios.

If asked something outside your knowledge:
- Be honest: "I don't have that information available"
- Offer alternatives: "I can transfer you to someone who can help"

Using Variables

You can reference system variables and custom variables in your prompt using {{variable_name}} syntax. System variables (always available):

Variable	Description
`{{agent_name}}`	Name of the current agent
`{{agent_id}}`	Unique identifier for the agent
`{{agent_number}}`	Agent’s phone number
`{{current_time}}`	Current time (HH:MM)
`{{current_date}}`	Current date (YYYY-MM-DD)
`{{current_datetime}}`	Date and time in ISO format
`{{current_day}}`	Day of the month (1–31)
`{{current_month}}`	Month (1–12)
`{{current_year}}`	Year (YYYY)
`{{current_weekday}}`	Day of the week
`{{current_timestamp}}`	Timestamp in milliseconds
`{{call_id}}`	Unique call identifier
`{{call_type}}`	Type of call
`{{call_start_time}}`	When the call began
`{{direction}}`	`inbound` or `outbound`
`{{user_number}}`	Caller’s phone number
`{{user_number_area_code}}`	Caller’s area code

For dynamic business-specific data (e.g., working hours, customer info), use custom variables passed as params when initiating the call. See Variable System for details.

Jinja2 Templates

Beyond simple substitution, prompts support full Jinja2 template syntax — conditionals, filters, and expressions are all available.

{% if direction == "outbound" %}
Hi {{customer_name}}, this is {{agent_name}} from Acme Corporation.
{% else %}
Thank you for calling Acme Corporation. I'm {{agent_name}}.
{% endif %}

Welcome{% if customer_name %}, {{customer_name}}{% endif %}!
Your balance is {{balance | default("unavailable")}}.

Templates are processed server-side before the prompt reaches the LLM. See the Jinja2 Template Designer Documentation for the full syntax reference. Example:

You are {{agent_name}}.
Today is {{current_date}} and the time is {{current_time}}.
The caller's number is {{user_number}}.
Working hours: {{working_hours}}

Prompt Settings

Below the prompt editor, two settings control how your prompt is processed: Enhanced Turn Taking — Enables better numeral capturing and backchannel detection for more natural conversations. Default: Off. Prompt Enhancer — Applies automatic enhancements to your prompt before it reaches the LLM:

Option	Description
Disabled	Your prompt is used as-is
Basic (default)	Stable, model-agnostic prompt enhancements
Advanced	Model-aware prompts with live context

Tool Integration

When your agent uses tools, include clear instructions for when and how to use them:

To check product availability:
1. Ask for the product name or SKU
2. Use the check_inventory tool
3. Based on results:
   - In stock: "We have that available. Would you like to place an order?"
   - Out of stock: "That's currently out of stock."
   - Discontinued: "That product has been discontinued. Can I suggest an alternative?"

Common Mistakes

Too vague:

You are a helpful assistant. Answer questions.

Better:

You are a customer support specialist for Acme Corp. Help customers
with product questions, order tracking, and returns. Use the knowledge
base for product details.

Conflicting instructions:

Be extremely brief. Provide detailed, comprehensive answers with lots of context.

Better:

Give concise answers (2–3 sentences). If the customer wants more detail,
offer to elaborate: "Would you like me to explain that further?"

Next Steps

Voice Settings

Configure voice and language options

Call Behavior

Set up response timing and interaction controls

Intelligence Features

Enable smart features like gender detection and smart call end

Knowledge Base

Add reference materials for your agent

Dashboard

Agents

Publishing

Variables

Tools

Knowledge Base

Batch Calls

Call History

Phone Numbers

Configuration

Writing Effective Prompts

Overview

Recommended Structure

1. Identity & Role

2. Personality & Tone

3. Response Guidelines

4. Task & Goals

5. Guardrails

6. Edge Case Handling

Using Variables

Jinja2 Templates

Prompt Settings

Tool Integration

Common Mistakes

Next Steps

Voice Settings

Call Behavior

Intelligence Features

Knowledge Base

​Overview

​Recommended Structure

​1. Identity & Role

​2. Personality & Tone

​3. Response Guidelines

​4. Task & Goals

​5. Guardrails

​6. Edge Case Handling

​Using Variables

​Jinja2 Templates

​Prompt Settings

​Tool Integration

​Common Mistakes

​Next Steps

Voice Settings

Call Behavior

Intelligence Features

Knowledge Base

Overview

Recommended Structure

1. Identity & Role

2. Personality & Tone

3. Response Guidelines

4. Task & Goals

5. Guardrails

6. Edge Case Handling

Using Variables

Jinja2 Templates

Prompt Settings

Tool Integration

Common Mistakes

Next Steps