Glossary
The terms the documentation uses all the time, explained in one paragraph each, with the guide where the subject is covered in full.
Each route’s contract is in the API reference.
24-hour window#
The period in which you can send a free-form message (text, image, buttons) to a contact: 24 hours after the last message they sent to your number. The contact opens the window, by writing; sending a template does not open it. With the window closed, only a template goes out, and sending free-form text answers 409 with error: "window_closed". More in Send messages.
Template#
A message model that Meta approves before use. It is the only way to start a conversation, or to talk to someone outside the 24-hour window. Its state (PENDING, APPROVED, REJECTED...) comes from Meta, and only APPROVED sends. More in Templates.
Idempotency#
The property of a call that, repeated, produces the same result as once. On Luna, you send the Idempotency-Key header with a value of yours in POST /v1/messages: if the call is repeated (after a timeout, for example), Luna returns the original message instead of sending a second one. More in Send messages and, for agents, in AI agent.
BSUID#
The user identifier that Meta gives each person, and which does not depend on the phone. Some people write without showing their phone number, and in that case the event arrives with a null wa_id and with the BSUID in user_id. To reply, use recipient with that value, in place of to. More in Users without a phone number.
Webhook#
An HTTPS address of yours that Luna calls (a POST) every time something happens: a message arrived, a message changed state, a number connected. It is how your system finds out without having to ask all the time. More in Receive events.
Signature#
The stamp Luna puts on every webhook delivery, in the X-Luna-Signature header, which proves the event came from it and was not changed. You redo the calculation with your secret and check. More in Receive events.
wamid#
The identifier of a message at Meta. It arrives after the send, over the webhook. The id the 202 returns is a different one: it is the message’s at Luna, and it is the one Luna’s routes ask for. More in Send messages.
externalId#
The label you give one of your customers (1 to 128 characters, free text). It is born on the connect link, goes to the number and comes back in that number’s events, so your system knows which customer each belongs to. Luna never interprets it. More in SaaS with N customers.
event_id#
The identifier of a webhook event. It is stable: the same delivery, repeated, carries the same event_id, and it is with it that your code drops what it has already handled. As delivery is at least once, repeats happen. More in Receive events.
Raw body#
The exact bytes your server received in the POST, before any reading of the JSON. The signature is calculated over them: if you open the JSON and build it again, the key order or the spaces can change and the check fails. Take the raw body from your library before parsing it. More in Receive events.