# Automation Triggers

> What starts an Avox automation - keyword, any message, business hours, no-reply follow-up, new contact and tag added - and when one runs.

Source: https://docs.theavoxai.com/automation/triggers

A **trigger** is what starts an automation. You pick it in step 1 (**Type**) of the
[Create automation wizard](https://docs.theavoxai.com/automation#step-type) and set it up in step 2
([Name](https://docs.theavoxai.com/automation#step-name)). An automation's trigger type is fixed once it's created; for a
**Keyword match** automation you can still edit the keywords on the canvas.

| Trigger | Starts when | Settings |
| --- | --- | --- |
| [Keyword match](#keyword-match) | A message contains one of your keywords | Keywords |
| [Any message](#any-message) | Any message arrives | None |
| [Outside business hours](#outside-business-hours) | A message arrives outside your opening hours | Opens at, Closes at, Timezone |
| [New contact](#new-contact) | A contact sends their very first message | None |
| [No-reply follow-up](#no-reply-follow-up) | Nobody has replied after a set wait | Minutes to wait before following up |
| [Tag added](#tag-added) | An automation adds one of your tags to a contact | Tags to watch for |

## Keyword match

"Fires when a customer's message contains one of your chosen words or phrases."

- **Settings:** **Keywords** - type a word or phrase and press Enter (or type a comma) to add it
  as a chip. Click a chip's x to remove it, or press Backspace in the empty field to remove the
  last one; the same keyword can't be added twice. Add at least one ("Add at least one keyword").
  You can change the keywords later right on the canvas's trigger box.
- **Matching:** the automation fires when the message contains any one of the keywords, anywhere
  in the text. Upper and lower case don't matter, so `hours` matches "What are your HOURS?".
- **Tip:** a short keyword matches inside longer words too - `book` also matches "booking" and
  "notebook". Use a phrase when you need to be specific.

## Any message

"Fires on every message a customer sends you - a catch-all auto-reply."

- **Settings:** none.
- **Use it for:** a general acknowledgement, often combined with a
  [condition](https://docs.theavoxai.com/automation/builder#conditions-and-branches) to handle specific words differently.

## Outside business hours

"Fires only when a customer messages you outside your set opening hours."

- **Settings:** **Opens at** and **Closes at** in 24-hour time (defaults 09:00 and 18:00), and a
  **Timezone**. The wizard detects your device's timezone ("Detected from this device: ...") and
  lists every timezone with its UTC offset, ordered west to east.
- **Matching:** Avox compares the time each message arrives with your hours, using the UTC offset
  shown next to the timezone you picked. The automation fires outside the window and stays quiet
  inside it.
- **Overnight hours work too.** With **Opens at** 22:00 and **Closes at** 06:00, the automation
  fires between 06:00 and 22:00.
- **Summary:** the automation shows as "Fires outside 09:00 to 18:00" (with your own times).

## New contact

"Fires only on a contact's very first-ever message to you - a real welcome message."

- **Settings:** none.
- **Matching:** fires when a contact has no earlier incoming message in Avox. Messages synced in
  from the WhatsApp Business App count as earlier messages, so a customer whose past chats were
  synced isn't treated as new. A contact who was only synced from your address book, with no
  messages yet, still is. See [Coexistence sync](https://docs.theavoxai.com/connections/coexistence).

## No-reply follow-up

"Fires if nobody's replied to a customer after a set number of minutes."

- **Settings:** **Minutes to wait before following up** (30 by default). Set 1,380 minutes
  (23 hours) or less, so the follow-up always lands inside Meta's
  [24-hour messaging window](https://docs.theavoxai.com/whatsapp/messaging-window). Avox only follows up within that window.
- **Summary:** "Fires after 30 minutes of no reply" (with your own wait). In the **Your
  automations** table this trigger is listed as **Follow-up (no reply)**.
- **Matching:** Avox checks every minute for contacts whose latest message is one *they* sent,
  older than your wait time, with nothing sent back since - not by your team in the
  [Inbox](https://docs.theavoxai.com/inbox), not from the WhatsApp Business App on your phone, not by the Avox API, and not by
  another automation. When it finds one, the follow-up runs.
- **Once per unanswered message.** Each unanswered message gets at most one follow-up. If the
  customer writes again, that new message starts its own wait.
- **Recent conversations only.** Avox looks at messages from your wait time up to two hours beyond
  it, so switching the automation on doesn't send follow-ups into old conversations.
- **Connected numbers only.** A number that is paused or disconnected is skipped until it's
  connected again.
- The one-hour cooldown below applies too.

> **Tip**
>
> The premade **No-reply follow-up** automation (named "Follow-up nudge") is the quickest start: it
> sends "Sorry for the wait - just checking in, we'll have an answer for you shortly!" and tags the
> contact `followed_up`. Change the text to fit your business.

## Tag added

"Fires when a specific tag gets applied to a contact - chain automations off one another."

- **Settings:** **Tags to watch for** - one or more tags, added as chips. "Fires once, the moment
  any of these tags gets applied to a contact - including by another automation's own "Tags &
  categories" step." Add at least one ("Add at least one tag to watch for").
- **Matching:** fires when an automation's **Tags & categories** step adds one of these tags to a
  contact who didn't already have it. Upper and lower case don't matter. Re-adding a tag the
  contact already has doesn't fire it again.
- **Chains:** one automation can tag a contact, which starts a Tag added automation, which can tag
  again. Avox limits how deep such a chain goes, so automations can't set each other off in a loop.
- **No incoming message:** a Tag added automation starts from a tag, not a message, so a
  **Condition** in it never matches and **Mark as read** has nothing to mark. Use sends and tags.
- **Summary:** "Fires when tagged: VIP" (with your own tags).

## When an automation runs

These rules apply to every trigger:

**1. A new message arrives**

Each new incoming message is checked once. A message Meta delivers twice is still only checked
once. (**No-reply follow-up** automations are the exception: they're checked every minute
instead, as described above.)

**2. Avox finds the first match**

Avox goes through the Switchboard's **switched-on** automations from oldest to newest and picks
the first whose trigger matches. Only that one automation runs for the message.

**3. The one-hour cooldown is checked**

An automation runs at most once per hour for the same contact. If it already ran for this
contact in the last hour, nothing runs for this message. This stops a fast back-and-forth from
turning one automation into a stream of replies.

**4. The actions run**

The actions run in order. Each message sent spends [credits](https://docs.theavoxai.com/automation/credits).

> **Tip**
>
> Because the oldest matching automation wins, keep your most specific automations (for example a
> Keyword match) older than broad ones such as **Any message**, or the broad one can answer first.

### When nothing runs

- **No active subscription** - automations send only while the Switchboard has an active plan.
- **Out of credits** - sending stops until credits reset ([AVX-3076](https://docs.theavoxai.com/error-codes/avx-3076)).
- **Connection paused for billing** - when a canceled subscription pauses your connection, each
  automation that would have run is recorded on [Logs](https://docs.theavoxai.com/logs) as a failed `automation_skipped`
  event with "This automation didn't fire - the connection is paused because this Switchboard's
  subscription was canceled." Filter Logs by that event type to see them all. See
  [AVX-3082](https://docs.theavoxai.com/error-codes/avx-3082).
- **Connection not connected** - while a number is paused or still being set up, its automations
  don't run. They pick up again with the next message after it's connected.
- **On cooldown** - the first matching automation already ran for this contact in the last hour.
- **Switched off** - only automations with the **Active** switch on are checked.

### The messaging window

Automations reply to messages as they arrive - or, for a no-reply follow-up, within 23 hours of the
customer's message - so their replies go out inside WhatsApp's
[24-hour messaging window](https://docs.theavoxai.com/whatsapp/messaging-window), where free-form messages are allowed.