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

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). 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). 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); 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 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.