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

# Automations Overview

> The three ways Xobito can reply to your customers automatically — Message Bots, Template Bots, and Bot Flows.

Xobito ships with three different automation tools. They look similar at first glance but solve quite different problems. Picking the right one is the difference between an automation that quietly does its job and one you keep having to patch.

<Note>
  All three types react to inbound messages the same way — they look at what the customer sent, match it against a trigger, and run. The difference is **what happens next**.
</Note>

## The three types

<CardGroup cols={3}>
  <Card title="Message Bots" icon="reply" href="/automations/message-bots">
    One keyword in, one reply out. Plain text plus up to three quick-reply buttons.
  </Card>

  <Card title="Template Bots" icon="envelope" href="/automations/template-bots">
    A keyword triggers an approved WhatsApp template with filled-in parameters.
  </Card>

  <Card title="Bot Flows" icon="diagram-project" href="/automations/bot-flows">
    Full visual builder — branching conversations with media, list pickers, API calls, and more.
  </Card>
</CardGroup>

## Quick comparison

|                                          | Message Bot                      | Template Bot                                        | Bot Flow                                                              |
| ---------------------------------------- | -------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
| **What it sends**                        | Plain text + up to 3 buttons     | One approved WhatsApp template                      | Any combination of text, media, lists, buttons, API calls, AI replies |
| **Conversation length**                  | Single reply — stateless         | Single template — stateless                         | Multi-step — branches follow button choices                           |
| **Storage shape**                        | Flat database row                | Flat database row                                   | JSON graph of nodes and edges                                         |
| **Can send outside the 24-hour window?** | No — plain messages only         | Yes — templates bypass the session window           | Only if the flow sends a template node (future)                       |
| **Complexity to build**                  | Very low — one form              | Low — pick a template, fill in parameters           | Higher — visual builder with up to 10 node types                      |
| **Best for**                             | "Hours", "Address", "Price list" | Welcome or re-engagement template sent on a keyword | Menus, lead qualification, multi-question flows                       |

## All three share the same trigger rules

Every bot — Message, Template, or Flow — asks the same two questions at setup:

1. **Who does this apply to?** (`rel_type`)
   * `lead` — only fires for contacts marked as leads
   * `customer` — only fires for contacts marked as customers

2. **When does it fire?** (`reply_type`)
   * **1 — On exact match** — the incoming message text equals a keyword exactly
   * **2 — When message contains** — the incoming message contains a keyword as a substring
   * **3 — On first message** — the contact is messaging you for the first time
   * **4 — If no keyword matches** — fallback when nothing else caught the message

For types 1 and 2 you supply a comma-separated list of keywords. For types 3 and 4 the keyword field is ignored.

<Tip>
  The four reply types are shared across all three bot types. Once you learn them here they apply everywhere.
</Tip>

## How to choose

<AccordionGroup>
  <Accordion title="Use a Message Bot when...">
    * The question always has the same answer — "What are your hours?", "Where are you based?", "What's your phone number?"
    * You want a quick acknowledgement like "Thanks, we'll get back to you shortly" while an agent is being paged.
    * You're happy with plain text and at most three buttons.

    Message Bots are the fastest thing to set up. If a Bot Flow feels like overkill, reach for one of these.
  </Accordion>

  <Accordion title="Use a Template Bot when...">
    * You need to send a **pre-approved** WhatsApp template (for example to reopen a conversation that's outside the 24-hour session window).
    * The content is longer than a Message Bot allows, or needs header media or structured buttons.
    * You want to send a branded welcome template when a contact messages for the first time.

    Template Bots are the only way to send a template in response to a trigger without building a full flow.
  </Accordion>

  <Accordion title="Use a Bot Flow when...">
    * The conversation has more than one step — "Ask the customer for their order number, then look it up, then route them."
    * You need buttons that lead to different outcomes.
    * You want to send media (images, video, documents), share a location, or collect data via an external API.
    * You want to hand over to an AI Assistant (if that module is enabled).

    Bot Flows are the most flexible — and the most work.
  </Accordion>
</AccordionGroup>

## Can I use them together?

Yes, and most workspaces do.

<Steps>
  <Step title="A Message Bot handles the greeting">
    Customer types "Hi" — a Message Bot replies with a friendly welcome and a hint: "Type MENU to see options".
  </Step>

  <Step title="A Bot Flow handles the menu">
    Customer types "MENU" — a Bot Flow takes over with a list of options, branches on the button they press, and routes them.
  </Step>

  <Step title="A Template Bot handles re-engagement">
    A few days later, if the contact has been quiet, a Template Bot sends a check-in template.
  </Step>
</Steps>

## What controls whether a bot runs?

Each bot has a feature flag on the workspace subscription:

| Bot type      | Feature slug    |
| ------------- | --------------- |
| Message Bots  | `message_bots`  |
| Template Bots | `template_bots` |
| Bot Flows     | `bot_flows`     |

If a feature isn't part of your plan, that bot type won't appear in the sidebar. Ask your workspace owner to check the subscription if you expect to see it and don't.

Each bot also has an active / inactive toggle. When inactive, it's saved but won't fire on incoming messages.

## Variables

All three bot types let you personalise replies with merge fields like `{contact_first_name}`. These use **single curly braces** and are different from template variables (which use `{{1}}`, `{{2}}`, etc.).

The available merge fields are:

```
{lead_status}
{lead_source}
{lead_assigned}
{contact_first_name}
{contact_last_name}
{contact_id}
{contact_company}
{contact_email}
{contact_phone_number}
```

<Note>
  Custom fields are **not currently available** as merge fields inside automations — only the predefined fields above are substituted.
</Note>

## Activity logging

Every time a bot is created, edited, enabled, disabled, or deleted, an entry lands in the [Activity Log](/team/activity-log). Use that log when a bot's behaviour changes unexpectedly and you need to see who touched it.

## Permissions

Each automation has its own permission group. Hand them out through [Roles & Permissions](/team/roles-permissions):

| Permission prefix       | What it unlocks                                   |
| ----------------------- | ------------------------------------------------- |
| `tenant.message_bot.*`  | Message Bots — view, create, edit, delete, clone  |
| `tenant.template_bot.*` | Template Bots — view, create, edit, delete, clone |
| `tenant.bot_flow.*`     | Bot Flows — view, create, edit, delete            |

Staff who only need to read how an automation is configured should have **View** only.

## What to read next

<CardGroup cols={3}>
  <Card title="Message Bots" icon="reply" href="/automations/message-bots">
    Keyword → reply in under two minutes.
  </Card>

  <Card title="Template Bots" icon="envelope" href="/automations/template-bots">
    Keyword → approved WhatsApp template.
  </Card>

  <Card title="Bot Flows" icon="diagram-project" href="/automations/bot-flows">
    Visual builder for multi-step conversations.
  </Card>
</CardGroup>