> For the complete documentation index, see [llms.txt](https://manuals.dialox.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manuals.dialox.ai/smart-receptionist/content-settings/content-section/message-templates.md).

# 12. Message templates

How the receptionist takes a message (what it asks, in which order) and what the email or note that it sends looks like.

A message template defines **how a message is taken** and **what the resulting email (or note) looks like**. The default template is **Callback request**. 2. Front desk picks the default template. A topic, 8. Spam calls and 9. Emergencies can each pick a different one.

<figure><img src="https://3570729730-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHmRSkEkoJwaBZ2OeQbHM%2Fuploads%2FLrPQAMqMeVg6dsSCicDf%2Fni-17-c12-template-expanded.png?alt=media&amp;token=d3e16b0a-7569-4a0d-8642-48ee18eb2125" alt="The Callback request template in Content → 12. Message templates"><figcaption><p>The Callback request template in Content → 12. Message templates</p></figcaption></figure>

## Fields per template

| Field                            | What it does                                                                                                                                                                                                           |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Label** (required)             | The name other sections show when they point to this template.                                                                                                                                                         |
| **Key**                          | How other sections refer to the template (for example `callback_request`). **Changing it breaks those references.**                                                                                                    |
| **How to hold the conversation** | Tone, order and what not to do, for example *"Keep it short and friendly, and ask one thing at a time. Never ask again for something the caller already said in this conversation."* Type `/` to insert a variable.    |
| **What to ask**                  | The fields the receptionist collects, in the order it should normally ask. See below.                                                                                                                                  |
| **Message subject**              | The subject of the email or note. Type `/` to insert a variable: a field from *What to ask*, or a value the receptionist fills in itself (company, callback summary, subject of the call, time, conversation link).    |
| **Message body**                 | The message itself. Type `/` to insert a variable. To leave out a line when a value is empty, wrap it in `{% if details != blank %} … {% endif %}`. See [Writing the subject and body](#writing-the-subject-and-body). |

Use **Test this form** to try the template, and **Add** to create a new one.

## What to ask

The default Callback request asks for:

| Field             | Example question                               | Mandatory | When the value is already known |
| ----------------- | ---------------------------------------------- | --------- | ------------------------------- |
| `user.first_name` | May I have your name?                          | Yes       | Use it, don't ask               |
| `user.phone`      | On which phone number can we call you back?    | Yes       | **Confirm it with the caller**  |
| `reason`          | What would you like us to call you back about? | Yes       | Use it, don't ask               |
| `best_time`       | When can we best reach you?                    | No        | Use it, don't ask               |

Open a field to change its **Stored as** variable, **Example question**, **Mandatory** switch, and **When the value is already known**: *Use it – do not ask*, *Confirm it with the caller* or *Ask again anyway*.

* **Example question** is set **per language**. Usually it's a guide: the receptionist words its own question in the caller's language. When the receptionist has to ask for a missing field itself, it says the example question as written, so fill it in for every language.
* **"Known"** means known before the conversation, such as a returning caller's name or number. Whether a caller counts as returning depends on **Recognise returning callers** in [Settings → Call handling](https://manuals.dialox.ai/smart-receptionist/content-settings/settings-section/call-handling.md).

**A message is only complete when every mandatory field has a value**, and every known value marked *Confirm* or *Ask again* has been confirmed by the caller.

{% hint style="info" %}
**Asking for a department is not a subject.** A caller who only asked for a department (*"Sales, please"*) hasn't said what the call is about. When a message is taken for them, the receptionist asks what it is about, so `reason` is never just *"put me through to Sales"*.
{% endhint %}

**On a call, a phone number is read back.** When the caller says a number, the receptionist reads it out and asks whether it's correct. After a no, the caller keys it in on the keypad, finished with the hash key. The lines are **Phone number: read back** and **Phone number: key it in** in [11. Phrases](https://manuals.dialox.ai/smart-receptionist/content-settings/content-section/phrases.md).

## Writing the subject and body

The **Message subject** and **Message body** are written in **Liquid**, a simple templating language. You put a value in with `{{ name }}`, and you make parts of the message conditional with `{% … %}` tags. **How to hold the conversation** is rendered with Liquid too, so everything below works there as well.

Type `/` in a field to pick a variable from a list. The picked variable is inserted as `{{ name }}`.

{% hint style="info" %}
The **Phrases** section looks similar, but works differently. It fills in placeholders such as `{{company}}`, and doesn't support the tags and filters on this page. Everything below applies to message templates only.
{% endhint %}

### Variables you can use

These are the most useful ones. The `/` menu shows the full list.

| Variable                                                                                    | What it contains                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{ user.first_name }}`, `{{ user.last_name }}`, `{{ user.phone }}`, `{{ user.email }}`     | What is known about the caller                                                                                                                                                                                 |
| `{{ caller_name }}`                                                                         | The name the caller gave during this call                                                                                                                                                                      |
| `{{ caller_id }}`                                                                           | The number the caller called from, or "anonymous"                                                                                                                                                              |
| `{{ company }}`                                                                             | Your company name (from 1. Company)                                                                                                                                                                            |
| `{{ assistant }}`                                                                           | The receptionist's name (from 10. Persona)                                                                                                                                                                     |
| `{{ subject }}`                                                                             | What the caller said the call is about, in a few words in your company's language, for example *"a quote for a new kitchen"*. Filled in by the receptionist, never asked for. Empty when the caller didn't say |
| `{{ callback_target }}`                                                                     | The department or person the message is for                                                                                                                                                                    |
| `{{ callback_summary }}`                                                                    | A short summary of the call, written by the AI                                                                                                                                                                 |
| `{{ callback_reason_text }}`                                                                | Why a message is taken, for example "nobody answered"                                                                                                                                                          |
| `{{ callback_time }}`                                                                       | Date and time of the call                                                                                                                                                                                      |
| `{{ conversation_link }}`                                                                   | Link to the conversation in Studio                                                                                                                                                                             |
| `{{ conversation.locale }}`                                                                 | The language of the conversation                                                                                                                                                                               |
| `{{ reason }}`, `{{ details }}`, `{{ best_time }}`, and any other field under *What to ask* | The answers the receptionist collected                                                                                                                                                                         |

A variable with no value renders as nothing, and the template doesn't fail.

### The basics

* **Show a value:** `{{ reason }}`
* **Show a line only when a value is filled in:** `{% if best_time != blank %}Best time: {{ best_time }}{% endif %}`
* **Show a line only when a value is empty:** `{% if details == blank %}No further details.{% endif %}`
* **Choose between two texts:** `{% if callback_target != blank %}for {{ callback_target }}{% else %}for the front desk{% endif %}`
* **Fall back to another value:** `{{ user.first_name | default: "Unknown caller" }}`
* **Change a value** with a filter: `{{ callback_target | upcase }}`, `{{ details | truncate: 200 }}`, `{{ reason | capitalize }}`

{% hint style="warning" %}
**Test for "has a value" with `!= blank`**, not with a plain `{% if details %}`. A plain `if` treats an empty field as filled in, so the line would show up with nothing after it. `!= blank` is only true when there is real text.
{% endhint %}

### Examples

**1. A short callback request**

```liquid
{{ user.first_name }} ({{ user.phone }}) called {{ company }}.

{% if subject != blank %}Subject: {{ subject }}
{% endif %}What it is about: {{ reason }}
{% if best_time != blank %}Best time to call back: {{ best_time }}
{% endif %}
Conversation: {{ conversation_link }}
```

**2. A sales lead, with optional details**

Subject:

```liquid
New lead: {{ user.first_name }}{% if details != blank %} - {{ details | truncate: 40 }}{% endif %}
```

Body:

```liquid
{{ user.first_name }} {{ user.last_name }} would like to be called back about: {{ reason }}

Phone: {{ user.phone }}
{% if user.email != blank %}E-mail: {{ user.email }}
{% endif %}{% if details != blank %}Details: {{ details }}
{% endif %}
Summary: {{ callback_summary }}
Call received: {{ callback_time }}
```

**3. A message that says why it was left**

```liquid
{% if callback_reason_text != blank %}This message was taken because {{ callback_reason_text }}.
{% endif %}Caller: {{ user.first_name | default: caller_name | default: "unknown" }}, {{ user.phone | default: caller_id }}
{% if callback_target != blank %}For: {{ callback_target }}
{% endif %}
{{ callback_summary }}
{{ conversation_link }}
```

{% hint style="info" %}
A mistake in a template doesn't stop the receptionist. The message goes out with `# ERROR: …` in place of the subject or body. Try a new template with **Test this form** before you use it.
{% endhint %}

## How it shows in a conversation

In this test the visitor asked about an invoice (a topic set to **Note**). The receptionist:

1. Already knew the visitor's name and number, so it didn't ask for the name. Because `user.phone` is set to **Confirm**, it asked *"Can we call you back on …?"*.
2. Accepted a different number from the visitor.
3. Took the reason from what the visitor had already said, and didn't ask for the optional best time.
4. Sent the email to the front desk address and confirmed *"Thank you, I have written down your message."*

<figure><img src="https://3570729730-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHmRSkEkoJwaBZ2OeQbHM%2Fuploads%2FFqD8ws13oE3bL6JkrMgA%2Fsr2-t12-message-email-and-note.jpg?alt=media&amp;token=dbb68b70-8267-4767-abab-9fc2dc6fd23d" alt="The email the receptionist sent, and the note kept in the inbox (personal data blurred)"><figcaption><p>The email the receptionist sent, and the note kept in the inbox (personal data blurred)</p></figcaption></figure>

The email follows the template's subject and body. Because **Settings → Messages & notifications → Also keep a note of e-mailed messages** is on, a copy is also kept as a note in the inbox and marked done. That's why it's shown struck through.

## More about Liquid

The language itself, with all its tags and filters, is described in the [Liquid reference](https://shopify.github.io/liquid/). DialoX uses an Elixir implementation of Liquid, which follows that reference, with one difference that matters here: a filter can't be used inside an `if` condition, so `{% if details | size > 0 %}` doesn't work. Use `{% if details != blank %}` instead.

## Related settings

What happens with a message once it's taken (a note of e-mailed messages, a caller who hangs up mid-message, an SMS about every message) is set under **Settings →** [**Messages & notifications**](https://manuals.dialox.ai/smart-receptionist/content-settings/settings-section/messages-and-notifications.md).
