> ## 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.

# Message Bots

> Match a keyword on an incoming message and send back a single reply — plain text plus up to three quick-reply buttons.

A **Message Bot** is the simplest form of automation in Xobito. A customer sends a message, the bot checks whether it matches one of your triggers, and if it does it sends **one reply** and stops.

<Note>
  Message Bots are **stateless**. They don't remember that they replied to this contact a minute ago, and they don't continue the conversation. If you need a multi-step back-and-forth, use a [Bot Flow](/automations/bot-flows).
</Note>

## What a Message Bot can send

A single outgoing message that contains:

* **Reply text** — the body of the message.
* **Header** (optional) — short text shown above the body.
* **Footer** (optional) — short text shown below the body.
* **Up to three buttons** — quick-reply buttons (`button1`, `button2`, `button3`). Each button just echoes its label back as a message — it does **not** branch the conversation like a Bot Flow does.

That's it. No media, no list picker, no API call — for those you want a Bot Flow.

## Create a Message Bot

Go to **Automations → Message Bots** and click **Create**.

<Steps>
  <Step title="Name it">
    Give the bot an internal name — e.g. "Business hours reply" or "Price list auto-answer". Customers never see this.
  </Step>

  <Step title="Pick who it applies to">
    Choose **Lead** or **Customer** — the bot will only fire when the contact has that relationship type.
  </Step>

  <Step title="Pick the trigger type">
    Choose one of the four reply types (see below).
  </Step>

  <Step title="Enter keywords">
    For exact-match and contains-match types, enter one or more keywords separated by commas. Leave empty for the other two types.
  </Step>

  <Step title="Write the reply">
    Type the reply text. Optionally add a header, footer, and up to three quick-reply buttons.
  </Step>

  <Step title="Save">
    The bot is live as soon as it's saved and active.
  </Step>
</Steps>

## The four trigger types

Every Message Bot uses one of these four rules to decide whether to fire:

| ID    | Name                  | When it fires                                                      | Keywords field                      |
| ----- | --------------------- | ------------------------------------------------------------------ | ----------------------------------- |
| **1** | On exact match        | The incoming message equals a keyword exactly (whitespace trimmed) | Required — comma-separated keywords |
| **2** | When message contains | The incoming message contains any of the keywords as a substring   | Required — comma-separated keywords |
| **3** | On first message      | The contact is messaging your business for the first time          | Ignored                             |
| **4** | If no keyword matches | Nothing else caught this message — the fallback                    | Ignored                             |

<Tip>
  Use **Type 4 (no keyword matches)** to build a catch-all "We'll get back to you shortly" reply. It runs only when none of your other bots fire.
</Tip>

### Examples

<AccordionGroup>
  <Accordion title="Exact match — 'hours'">
    * **Reply type:** 1 (on exact match)
    * **Keywords:** `hours, timings, open`
    * Fires only when the customer sends exactly "hours", "timings", or "open".
  </Accordion>

  <Accordion title="Contains match — greetings">
    * **Reply type:** 2 (when message contains)
    * **Keywords:** `hi, hello, hey`
    * Fires for "hi", "hi there", "hello team", "hey guys" — anything containing any of those words.
  </Accordion>

  <Accordion title="First message greeting">
    * **Reply type:** 3 (on first message)
    * **Keywords:** leave blank
    * Fires the first time a lead or customer ever messages your workspace.
  </Accordion>

  <Accordion title="Fallback reply">
    * **Reply type:** 4 (if no keyword matches)
    * **Keywords:** leave blank
    * Fires when none of your other bots caught the message. Useful as a polite "A team member will get back to you" message.
  </Accordion>
</AccordionGroup>

## Personalising the reply

Inside the reply text, header, and footer, you can insert any of these merge fields — they'll be replaced with real values when the bot runs:

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

Example:

```
Hi {contact_first_name}, thanks for messaging! Our hours are Mon-Fri 9-5.
```

<Warning>
  Custom fields are **not** yet available as merge fields inside Message Bots. Only the predefined fields above are substituted.
</Warning>

## Buttons

You can add up to three quick-reply buttons. Each button is just a label — when the customer taps it, WhatsApp sends the label back as their next message.

This means you can chain a button press into another bot:

* Message Bot A replies with buttons **"Pricing"**, **"Support"**, **"Hours"**.
* Message Bot B has trigger type 1 (exact match) with keyword `Pricing` — it fires when the customer taps the first button.

That's as close as Message Bots get to branching. For anything more complex, use a Bot Flow where buttons natively branch to different nodes.

<Note>
  Each button label can be up to 20 characters — the WhatsApp limit.
</Note>

## Activating and deactivating

Each Message Bot has an active / inactive toggle on its row. When inactive:

* The bot's configuration is kept.
* It will **not** fire on incoming messages.
* You can re-enable it at any time without re-entering anything.

This is handy for pausing a seasonal bot, or for temporarily turning off the fallback bot while you test a new one.

## Cloning

Use **Clone** to duplicate an existing bot. You get a copy you can then rename and tweak. Useful when you want near-identical bots for Lead vs Customer.

## Execution order

When a message comes in, Xobito checks automations in a defined order:

1. Bot Flows (if any is active and matches)
2. Message Bots (if no Bot Flow caught it)
3. Default greeting / away message (if configured)

If a Bot Flow's trigger matches the same keyword as a Message Bot, only the Bot Flow runs. If a Message Bot isn't firing, check whether a Bot Flow is catching the keyword first.

## Permissions

To manage Message Bots, a staff member needs one or more of:

| Permission                  | Allows                   |
| --------------------------- | ------------------------ |
| `tenant.message_bot.view`   | See the Message Bot list |
| `tenant.message_bot.create` | Create new bots          |
| `tenant.message_bot.edit`   | Edit existing bots       |
| `tenant.message_bot.delete` | Delete bots              |
| `tenant.message_bot.clone`  | Clone an existing bot    |

The workspace owner always has all of them.

## Feature availability

Message Bots require the `message_bots` feature on your subscription. If the Message Bots link is missing from the sidebar, your plan doesn't include them.

## What to read next

<CardGroup cols={2}>
  <Card title="Template Bots" icon="envelope" href="/automations/template-bots">
    Send an approved WhatsApp template on a trigger.
  </Card>

  <Card title="Bot Flows" icon="diagram-project" href="/automations/bot-flows">
    Branching multi-step conversations with media and APIs.
  </Card>
</CardGroup>