Events, rules and messages
Raven does not have a “send message” endpoint. You record that something happened; rules set in the instance decide who hears about it and on which channel. Posting an event is what makes Raven send.
Scope
Every event type has a scope. It decides which id the event must carry. A subject-scoped event names the subject either by subject_id, Raven’s id, or by subject_ref, the reference your own system gave it — exactly one of the two, and the event that comes back carries subject_id either way.
date_field and dedupe
Each type names the payload field that carries its date, so Raven can schedule reminders relative to it. Each type also lists dedupe_fields: two events of the same type, on the same subject, with the same values in those fields are one event.
Void
POST /events/{event_id}/void takes an event back and calls off the sends that have not gone. One already with the provider finishes; messages that went stay on record, and the event shows as voided. Nothing is deleted.
What arrives by SMS
The values you send are written into the instance's wording as they are, by WhatsApp and by email. By SMS they arrive in plain characters, unless the instance allows others under Settings: curly quotes and long dashes become plain ones, letters with accents the SMS alphabet lacks lose the accent, and emoji are left out, so every SMS part holds 160 characters. GET /messages shows the SMS as it went.
Codes
For a verification code, a one-time PIN or a temporary password, give the event type a field of the kind Code: "type": "string", "format": "code". Raven seals the code before anything is written and sends it to the recipient by SMS. Nobody else can read it afterwards: not on a screen, not through the API, not in the database.
POST /events
{ "type_key": "verification_code", "subject_ref": "SUB-2026-001", "payload": { "code": "482913" } }
SMS Your code is 482913. It expires in 10 minutes.
GET /events/{event_id} "payload": { "code": "••••••" }A code is 4 to 32 SMS characters with no spaces. A wording that uses one goes by SMS (or by WhatsApp first, below), at once, with no staff copies and no email, and fits in one SMS with the code counted at 32 characters. A code decides nothing: it cannot be a rule's condition, a dedupe field or the event's date, and events that carry one cannot come by file. GET /events and GET /messages answer •••••• in its place, always.
A code lives at most 24 hours, and is destroyed as soon as its message has gone. A message that could not go before then fails with hidden_value_gone, and nothing is sent.
An organisation may turn on Send codes by WhatsApp first in its Raven settings. A code whose wording is an approved WhatsApp authentication template then goes by WhatsApp first, in the message Meta writes for every business (482913 is your verification code. For your security, do not share this code., with a Copy code button and, if the wording says so, how long the code lasts). If Meta has not delivered it within the authentication wait (2 minutes by default, 1 to 15), the same code goes by SMS. A code of more than 15 characters goes by SMS at once, since Meta's template takes 15 at most. The event, the messages and the •••••• mask are the same either way. A link never goes by WhatsApp.
A sign-in, password-reset or verification link works the same way, as a field of the kind Secret link ("format": "secret_link"). It starts https://, is 12 to 100 characters, and must go to one of your organisation's proven web addresses, which your organisation proves with a DNS record under Web addresses in its account (*.acme.com covers login.acme.com, not acme.com). Any other is refused with a 400; when the addresses cannot be checked just then, a 503 asks you to try again. It is answered as https://login.acme.com/••••••. Phones and messaging apps may open a link to preview it, which uses up a link meant to work once: the page it opens should ask the person to press a button before it signs them in or resets anything.
Links and buttons
A field of the kind URL ("format": "url") holds a web address for a message to open: an invoice, a booking, a form. It must start https:// and is at most 2,000 characters; Phone ("format": "phone") is a number in full, like +231770000000, and Email an address. Each is checked when the event arrives, and refused with a 400 in plain words.
A wording can turn them into buttons. In an email the button opens your address as it is. On WhatsApp, Meta fixes the start of a button's address when it approves the wording, so the button opens https://go.utilitay.com/…, a link made for that one message, which goes straight on to your address when your organisation has proven its domain, and otherwise shows a page naming where it goes first. An SMS carries the address as text. A field a button reads has to be a required field of its event type.
Promotions
A wording written as marketing goes by WhatsApp only, to the contacts who have agreed to promotions and have not stopped since, at most twice a week each by default, within the business's marketing hours, and never while the number's quality is red. Record an agreement on a contact with marketing_consent; a person stops by tapping Stop promotions on any such message, by replying STOP PROMOTIONS, or in WhatsApp itself, and starts again with START PROMOTIONS. Notices they are expecting are not promotions and are unaffected.