---
title: Rules — what Talemo writes to clients, and when
summary: A rule says when something happens to a visit, for which visits and what Talemo writes to the client. The three notices of a visit are the built-in rules of each branch; more are added in words. A rule shows what it would do before it starts, a client gets at most three automatic messages in a day, and a rule pauses when the person it runs for leaves or loses the right.
tools: [talemo_list_rules, talemo_get_rule, talemo_create_rule, talemo_update_rule, talemo_list_rule_firings]
related: [visit-notices, booking-rules, services-and-prices, ../conversations/channel-window-and-templates, ../clients/reminders-opt-out, ../work/item-kinds]
search: [automatic messages to clients, reminder rule, confirmation rule, rule paused, message limit per day, WhatsApp template cost]
---

# Rules

A **rule** says when something happens to a visit, for which visits and what Talemo writes to the
client. It has three parts:

- **When** (`event`): some hours before the visit starts (1 to 72), or something happens to the
  visit — it is booked, moved or cancelled.
- **For which visits** (`conditions`): only visits of chosen services, service groups or masters,
  at most 50 of each. Nothing chosen means any visit; when several lists are chosen, a visit must
  fit all of them.
- **What** (`action`): write to the client one of three messages that go with the event. The
  **confirmation** goes with "booked" and "moved", the **reminder** with "hours before the visit",
  the **cancellation notice** with "cancelled". The words are those of the message template, a
  rule has none of its own (see
  [Channel window and WhatsApp templates](../conversations/channel-window-and-templates.md)).

Rules belong to a branch. `talemo_list_rules` lists them, and `talemo_get_rule` shows one. Each has
`created_by_name`, the name of the person who made it; it is left out for a built-in rule, when the
person is gone, or when they have no name. In the app the assistant shows them as the cards "Rules"
(`rules`, a branch) and "Rule" (`rule`, one rule with its history); in the web they are the card
"Clients" on the page "Booking rules".

## Built-in and added in words

The three notices of a visit — confirmation, reminder, cancellation — are the **built-in rules** of
every branch (see [Visit notices](visit-notices.md)). They work as they always did, and the booking
rules of the branch (`confirm_on_booking`, `remind_before_hours`) are the same settings: a change
in one is a change in the other (see [Booking rules](booking-rules.md)). Built-in rules change
less than the others: the confirmation can only be turned on or off, the reminder only gets other
hours, the cancellation notice cannot be changed, and none of them has conditions. Such a change is
refused with status 400, code `request.body_invalid` and `params.field` `enabled`, `event` or
`conditions`.

The others are added with `talemo_create_rule`, for example "remind about a manicure 2 hours before
the visit": `event` `{"on": "before_start", "hours": 2}`, `conditions` `{"services": [<service_id>]}`
and `action` `{"do": "write_to_client", "message": "visit_reminder"}`. The rule works at once. One
with `before_start` also takes the visits already booked whose hour has not come; one with `visit`
acts on what happens from then on. `talemo_update_rule` turns a rule on or off and changes its
time (`event`) and conditions, which replace the old ones whole. A new time moves the firings that
wait for their hour. Rules are not deleted: a rule that is not needed is turned off, and what it
did stays in the visits and in its list of firings.

A message that does not go with the event is refused with status 400, code `request.body_invalid`
and `params.field` `action`; hours out of range, an empty list of what happens to the visit or a
word named twice — with `event`; a list of more than 50 or a number named twice —
with `conditions.services`, `conditions.groups` or `conditions.masters`. A service, group or master
of another branch is refused with status 422, code `record.reference_missing` and the same
`params.field`. A rule of the whole business is changed only by a role of the whole business; for
any other role it is refused with status 403 and code `role.forbidden`. These refusals are
legitimate answers, not failures.

## What a rule would do

A rule writes to clients by itself, so before it starts, `talemo_create_rule` and `talemo_update_rule`
with `dry_run` show it with its **forecast** and change nothing. `talemo_get_rule` shows the
forecast of a rule that is already there. It has two windows: `ahead` — the next 14 days — and
`past` — the last 30 days, as if the rule had stood then. In each:

- `firings` — how many visits the rule fires on;
- `clients` — how many clients;
- `sends` — how many messages would go;
- `by_template` — how many of them would go as a WhatsApp template, outside the 24-hour window.
  Meta charges the business for these by its own rates, by country and category; the forecast
  counts the messages and does not count the sum, and the rates are in Meta's price list for
  WhatsApp Business;
- `skipped` — why the rest would not go, a reason and a count: for example `no_confirmed_contact`,
  `window_closed`, `template_not_approved`, `daily_limit`.

A rule with `visit` has nothing ahead to count: what happens to visits is not known in advance, and
the forecast ahead is empty; the last 30 days show what the rule would have done. Whether a message
would go is decided by the same rules as for a real one: the contact of the client, the window of
the channel, the approved template, the limit of the day.

## Three messages in a day

All rules together write to one client at most three automatic messages in any 24 hours. The
fourth is not sent and is skipped with `daily_limit`. The cancellation notice is not counted and is
never held back by this limit; replies of people in the chat and the word "stop" do not count
either.

## Whose rights, and pause

A rule runs with the rights of the person who made it, as if they had written the message
themselves. When that person leaves the business, or no longer has the right to change the
booking rules of the branch, the rule **pauses** (`state` `paused`, `pause.reason`
`creator_left` or `creator_lost_right`) and writes to nobody. It also pauses (`failures`) when its last
three sends did not go because of the rule itself: the channel is disconnected, the WhatsApp template
is refused, or the business has no payment method in WhatsApp. A failure of Meta or of Talemo, or one
that belongs to a single client (a number that cannot be reached, a closed window), is not counted, and
it does not break the three either. A paused rule is not lost: someone who may change the branch turns it on or
off with `talemo_update_rule`; the pause goes, and the person who did it becomes the one whose
rights the rule runs with. The count of three sends starts again from turning the rule on (and from
any change of the rule): old failures do not pause it again. Until then a case "rule paused" waits for everyone who may change the
branch of the rule (see [Kinds of items in Waiting for you](../work/item-kinds.md)); it goes away
by itself when the rule is turned on or off.

Talemo can also switch the rules made in words off in a business for now, for example after a problem
(`feature.off`, `params.feature` `rules_in_words`). Then `talemo_create_rule` is refused and is not in the
list of tools, the rules made in words that are on show as `paused` with `pause.reason` `feature_off`
and write to nobody, and there is nothing to turn back on: they work again by themselves when Talemo
switches the rules back on. The three built-in notices of a visit work as usual.

A rule that is on, but whose WhatsApp has no approved template of its message, has `state`
`waits_template`: inside the 24-hour window the message goes as text, outside it does not go until
Meta approves the template.

## What a rule did

`talemo_list_rule_firings` lists the firings of a rule, the newest first (`limit` 1 to 200, 50 when
left out). Each is one notice on one visit: `kind` (`confirmation`, `reminder` or `cancellation`) and
`state`: `planned` waits for its hour (`due_at`), `sent` went to the queue of the channel,
`skipped` did not go, `cancelled` was withdrawn because the visit was cancelled, done or moved.
`reason` says why one did not go (see [Visit notices](visit-notices.md) for the reasons of the
channel), and these are added by rules: `daily_limit`, with `limit` — how many messages a day a
client gets —, `has_later_visit`, when the rule writes only to a client with no later visit, and
`rule_paused`. `party_name` is the name on the card of the client. A sent one says how: `channel`,
`via` (`text` or a WhatsApp `template`) and `delivery` (`queued`, `sent`, `delivered`, `read` or
`failed`, with the `code` of the refusal). A waiting one that will not go by what Talemo knows now
has `expected_skip`, the reason. `activity` of a rule counts the firings that wait now and those
sent and skipped in the last 30 days.