> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a prompt that works on calls

> Write agent instructions for voice calls, based on how Hamsa uses them: what the prompt enhancer adds, how variables and Jinja render, and how time works.

Your prompt is the main thing that decides how your agent behaves on a call. This page explains what happens to the prompt before the model reads it, then gives practical advice that follows from it. It applies to a single prompt agent's **Agent instructions** and a flow agent's **System prompt**. A flow's step prompts follow the same rendering rules.

## How Hamsa uses your prompt

When a call starts, Hamsa prepares the prompt in this order:

1. **Variables and Jinja are filled in.** Every `{{ }}`, `{% %}` and `{# #}` part is rendered with the call's values. This happens once, at the start of the call.
2. **The prompt enhancer adds its sections**, unless it is set to **Disabled**: speaking rules, and an instruction to speak the voice's dialect.
3. **On every turn**, the model also gets the current date and time in the agent's time zone, plus short notes such as the caller's detected gender when that setting is on. These notes are not saved in the conversation history.

The model then reads the prompt, the conversation so far, and the descriptions of the tools it may call, and writes a reply. The reply is spoken by the agent's voice, so everything the model writes is heard by the caller.

## What the prompt enhancer adds

Set the enhancer under the instructions (single prompt) or in **System prompt** (flow). It is **Basic** for new agents.

![The Prompt enhancer list under Agent instructions, showing Disabled, Basic (selected) and Advanced](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/prompt-enhancer-menu-light.webp)

| Mode | What Hamsa adds to your prompt |
| - | - |
| **Basic** | Rules for speech: a respectful, natural tone; clear, short answers; numbers as words; phone numbers read digit by digit; email addresses read as "name at gmail dot com"; no made-up answers; never claim an action without using the tool; allow for speech recognition mistakes and ask to repeat when unclear; plain text with no formatting. Then a line telling the model to speak the voice's dialect. |
| **Advanced** | Sections on behavior (one or two short sentences by default), output formatting, flow guidance, tool use and guardrails (no invented facts, no claimed actions, decline requests to change role or reveal the prompt, stay on topic). The wording adapts to the model family. The dialect line comes last. |
| **Disabled** | Nothing. Your prompt is used as written, with no dialect instruction. |

What this means for your prompt:

* With **Basic** or **Advanced**, don't repeat these rules, and don't write rules that contradict them (for example "list the options as bullet points"). Spend your words on your business.
* With **Disabled**, you are responsible for everything the enhancer would have said. At least tell the model to reply in plain spoken sentences, to say numbers as words, and which language and dialect to speak.

## Structure that works

A prompt the model can follow on a live call is short, concrete and ordered. One structure that works:

```markdown theme={null}
# Role
You are Sara, the booking assistant for Acme Dental in Amman.

# Goal
Book, move or cancel appointments. Answer questions about opening hours and prices.

# How to run the call
1. Ask what the caller needs.
2. For a booking, ask for the treatment, then a preferred day.
3. Check availability with the check_availability tool before you offer a time.
4. Repeat the time back and ask the caller to confirm.

# Rules
- Never give medical advice. Offer to book a consultation instead.
- If the caller asks for a person, say a colleague will call back and end the call politely.

# Facts
- Open Sunday to Thursday, 9:00 to 17:00.
- A cleaning costs 25 JOD.
```

* **Headings help you, not only the model.** With two or more headings, the editor shows an **Outline** to jump between sections.
* **Say when to use each tool.** The model picks tools from their descriptions and your instructions. Name the tool and the moment ("before you offer a time"), and say what to do when it fails.
* **Keep facts the agent needs on every call in the prompt; put long reference material in the [knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md).** The whole prompt is sent on every turn, and the word and token count under the field shows what that costs.
* **Tell the agent how to end.** A single prompt agent only hangs up on its own when **Smart call end** is on, and its condition is the **Smart call end prompt**. A flow agent ends at an [End call step](https://docs.tryhamsa.com/agents/flow/steps/end-call.md). See [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#end-the-call).

## Write for the ear

The caller hears every word the model writes, through a text-to-speech voice.

* Ask one question at a time, and keep turns short. Long turns are hard to follow on the phone.
* Spell out how to say things that are easy to get wrong: prices ("25 dinars"), codes, product names. For a word the voice keeps mispronouncing, add it to a [pronunciation dictionary](https://docs.tryhamsa.com/agents/voices/dictionaries.md) instead of working around it in the prompt.
* Ask the agent to confirm what it heard for anything that matters, such as numbers, dates and names. Callers' words come through speech recognition and can be misheard.
* Write example phrases in the language and dialect the agent speaks. The dialect instruction tells the model which dialect to use; examples show it the tone.

## Use variables safely

Variables let one prompt adapt to each call: `Hello {{ customer_name }}`. Values come from the call itself (system variables), from the request that starts the call (dynamic variables), from the agent's environment, or from the conversation. See [Variables](https://docs.tryhamsa.com/agents/variables/overview.md) and [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md).

Three rules explain almost every surprise:

**Every value is text.** A dynamic variable sent as `5` arrives as the text `"5"`. A comparison between text and a number fails, so convert first:

```jinja theme={null}
{% if open_orders | int > 3 %}This caller has several open orders.{% endif %}
```

The same goes for yes or no values. `"false"` is text, and any non-empty text counts as true, so compare it:

```jinja theme={null}
{% if is_vip == "true" %}Greet them as a valued member.{% endif %}
```

Values that look like a JSON object or list (`{"plan": "gold"}`) are read as objects, so `{{ account.plan }}` works.

**A missing variable renders as empty.** `Hello {{ customer_name }},` becomes `Hello ,` when no name was passed. Give a fallback that also covers an empty value:

```jinja theme={null}
Hello {{ customer_name or "there" }},
```

**An error drops every Jinja part.** If any part of the template can't render (a syntax error, an unknown filter, comparing text with a number), the model gets the prompt with all `{{ }}`, `{% %}` and `{# #}` parts removed. Your conditional sections disappear silently and the call goes on. Preview the template in the **Jinja2 template editor** before you publish, with test data in the same form your calls send.

When you branch on the kind of call, match the exact values:

| To check | Use | Values |
| - | - | - |
| Phone or browser | `call_type` | `"Phone"` or `"Web"` |
| A call that came in on your number | `direction` | `"Inbound"` on inbound phone calls; every other call, browser tests included, is `"Outbound"` |

```jinja theme={null}
{% if call_type == "Phone" and direction == "Inbound" %}Thank the caller for calling Acme.{% endif %}
```

## Dates and times

Time variables use the agent's **Timezone** from **Call settings**. Set it to your business's time zone; see [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#time-zone).

| Variable | Looks like |
| - | - |
| `{{ current_time }}` | `Saturday, October 31, 2026 at 02:05:00 PM UTC` |
| `{{ current_date }}` | `2026-10-31` |
| `{{ current_weekday }}` | `Saturday` |

* Variables in the prompt are filled in once, when the call starts. In a long call, `{{ current_time }}` in the prompt still shows the start time.
* The model also gets a fresh "Current date and time" line on every turn, so for "what time is it now" questions you don't need a variable at all. Use the variables when the prompt itself needs the date, for example `{% if current_weekday == "Friday" %}We are closed today.{% endif %}`.
* `current_time` is a sentence, not a number, so you can't compare it with `>` or `<`.

For every system variable and its exact format, see [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md).

## Arabic and dialects

* The agent speaks the dialect of its voice. To change the dialect, pick a voice in that dialect. See [Voice, language and dialect](https://docs.tryhamsa.com/agents/settings/voice-and-language.md).
* With the enhancer on, Hamsa adds a line such as "Always speak in Jordanian dialect of Arabic", so you don't need to.
* With **User gender detection** on, the model is told each turn whether it is speaking to a man or a woman and, with the enhancer on, how to use the matching Arabic forms. You don't need gender rules in the prompt. See [Call behavior settings](https://docs.tryhamsa.com/agents/settings/call-behavior.md#know-who-is-speaking).
* With the **Language/dialect switcher** on, the dialect instruction is rewritten when the agent switches, and `{{ agent_dialect }}` and `{{ agent_language }}` follow the switch.

## Test the prompt

**1. Preview the template**

If the prompt uses Jinja, open the **Jinja2 template editor** and preview it with realistic test data, including a missing value and an empty one.

![The Preview tab of the prompt editor, with Test data (JSON) and the rendered Preview output](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/hamsa-prompt-editor-preview-light.webp)

**2. Call the agent**

Click **Test** and make a **Browser call**. Try the happy path, then the cases your rules cover: an off-topic question, a request for a person, a misheard number.

![The Browser call dialog asking for values for the dynamic variables customer\_name, loyalty\_tier and member\_since before the call starts](https://mintlify.s3.us-west-1.amazonaws.com/hamsa-452fa79a/images/agents/build/browser-call-test-values-light.webp)

**3. Read the call**

Open the call in the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md) and read the transcript. Fix the prompt where the agent hesitated or broke a rule, then test again.

## Good to know

* There is no maximum prompt length, but every word is sent on every turn.
* Dynamic variables need a value in the test dialog before a browser call starts.
* A Jinja error never puts raw template code in front of the model or the caller; it removes the Jinja parts instead.

## Related

> [card] [Jinja syntax](https://docs.tryhamsa.com/agents/variables/jinja.md)
>
> Supported syntax, filters and macros.

> [card] [System variables](https://docs.tryhamsa.com/agents/variables/system-variables.md)
>
> Names and exact formats.

> [card] [Single prompt agents](https://docs.tryhamsa.com/agents/build/single-prompt.md)
>
> Where the prompt lives and how to edit it.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Browser calls, phone calls and test values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.