Developers
Staff blocks and alerts
What your app shows staff on a booking, the buttons they can press, how to alert staff, how to leave a note, and how events reach your app.
Staff see bookings in three places: the Gantt chart, the booking list and the booking drawer. Your app can add to all three. It can also raise alerts, leave notes and hear about what happens to a booking.
Declare what you use in the manifest, under extension_points:
booking_blockswith theslotsyou fill:gantt_bar,list_rowanddrawer.staff_actionsset to true, if your drawer has buttons.events, the event types you want sent to you.
The three slots
| Slot | Where it appears | What it holds |
|---|---|---|
gantt_bar |
On the booking's bar in the Gantt chart | One badge |
list_row |
On the booking's row in the booking list | Up to two chip blocks |
drawer |
In the booking's detail drawer | Up to 20 blocks of any staff block type, top to bottom |
BookingNinja asks your app for these with POST /blocks. The request lists the slots it wants and up to 100 bookings. Your reply is keyed by booking ref. Leave a slot out when you have nothing to show. An empty answer is {}.
{
"bookings": {
"bkg_9d3f6e1a": {
"gantt_bar": [ { "type": "badge", "label": "Game ready", "icon": "dice", "tone": "success" } ],
"list_row": [ { "type": "chip", "label": "2 games", "tone": "info" } ],
"drawer": [
{ "type": "key_value", "rows": [ { "label": "Shelf", "value": "B3" }, { "label": "Condition", "value": "Good" } ] },
{ "type": "actions", "actions": [ { "id": "handed_out", "label": "Handed out", "style": "primary" } ] }
]
}
},
"valid_for_seconds": 300
}
How BookingNinja uses the answer is different for each slot:
- Gantt chart and list. These are shown from a copy BookingNinja keeps. They never wait for your app, because a page of bookings is drawn many times. BookingNinja fetches fresh blocks when a page looks stale, and reuses them for
valid_for_seconds(between 30 and 3600, default 300). If a fetch fails or breaks the contract, the copy it has stays. When something changes in your app, callPOST /api/v1/apps/blocks/refreshwith therefs of the bookings, up to 100, and BookingNinja fetches them again. - Drawer. BookingNinja asks your app live when staff open the booking, for that one booking, and reuses the answer for five seconds. If your app cannot be reached, staff see the last drawer your app sent, marked as the last known details, or a short warning if there is none.
BookingNinja only asks for bookings your app is attached to: the ones with a hold or a reservation from your app.
Staff block types
A drawer can use any of these. A block with unknown fields is cleaned: text is stripped of markup, lists are cut to their limits, and a block left with nothing to show is dropped.
| Block type | What it is for |
|---|---|
badge |
A small coloured label with an optional icon and tooltip. The Gantt slot's block. |
chip |
A short pill of text. The list slot's block. |
text |
A paragraph of plain text |
key_value |
Labelled values, such as a shelf and a condition. Up to 12 rows. |
image_list |
Items with their pictures. Up to 10. |
actions |
Buttons staff can press. Up to 5. Only shown when the manifest declares staff_actions. |
alert |
A boxed message that stands out: something staff must do or know |
stat |
One figure shown large with a label, such as a points balance |
meter |
A bar showing how full something is |
timeline |
What has happened, in the order you send it. Up to 20 entries. |
table |
A small table. Up to 6 columns and 20 rows. |
tags |
A row of small labels. Up to 12. |
people |
People on your side of the booking, such as an instructor. Up to 6. |
checklist |
Lines staff tick off. Up to 20. |
gallery |
Pictures staff may need, such as an item's condition. Up to 8. |
code |
A code staff need, such as a locker number. It can also draw a QR code. |
links |
Links out to your own pages for this booking. Up to 6, each opening in a new tab. |
Every block takes a tone where that makes sense: neutral, info, success, warning or danger. Icons come from a fixed set of 26 names. An unknown name falls back to a neutral icon. Links and pictures must be HTTPS.
Buttons and actions
A button is one entry in an actions block:
{
"type": "actions",
"actions": [
{ "id": "swap_game", "label": "Swap game", "input": "collection" },
{
"id": "add_note",
"label": "Add a note",
"input": "fields",
"fields": [ { "key": "note", "type": "textarea", "label": "Note", "required": true } ]
},
{ "id": "cancel_visit", "label": "Cancel visit", "style": "danger", "confirm": "Cancel this visit? The guest is not told." }
]
}
idnames the button and comes back asaction_id. It must be unique across the whole drawer: if two buttons share one, the first wins.styleisdefault,primaryordanger.confirmmakes BookingNinja ask staff to confirm, with your wording, first.inputiscollectionto open the catalogue picker first, orfieldsto open a small form first. A form takes up to 8 fields of any field type.
Your app must declare staff_actions in the manifest, or BookingNinja drops every actions block.
When staff press a button, BookingNinja calls POST /actions:
{
"context": {
"installation_id": "ins_8f2k4a9b",
"venue": { "id": "ven_41c7d2", "name": "The Games Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
"settings": { "venue": {}, "session": {} },
"booking": {
"ref": "bkg_9d3f6e1a",
"status": "confirmed",
"session": { "id": "ses_5e8a1c", "name": "Saturday play" },
"date": "2026-12-05",
"start": "14:00",
"end": "16:00",
"party_size": 4,
"tables": ["Table 7"],
"reservation_id": "res_77be1c"
}
},
"action_id": "add_note",
"actor": { "name": "Sam" },
"input": { "values": { "note": "Box was damp." } }
}
context.booking.reservation_id names the reservation the action is about. actor.name is the staff member's display name, for your own records.
A few rules:
- Only buttons you offered. BookingNinja accepts an action only if your app offered it in the drawer it last returned for that booking.
- Input is checked first. For a form, BookingNinja checks the values against the fields you declared before it calls your app. For a picker,
input.itemsholds the staff member's choice. - One press at a time. Presses for the same booking and the same action are handled one at a time. Each press has an
Idempotency-Key, so a repeat is a retry: return the first answer. - A checklist can tick. A line in a
checklistblock may carry anaction_id. Ticking it presses that action withinput.valuesset to{item, done}. Give the line an id of its own, not one a button already uses: a line that shares a button's id is shown as a read-only tick. A line with noaction_idis for display only. - Payments are never touched. An action cannot take or refund money.
Your reply says what to change:
{
"message": "Note added.",
"drawer": [
{ "type": "text", "text": "Box was damp." }
]
}
messageis a short toast for staff, 200 characters at most.drawerreplaces the drawer's blocks. A drawer in an action reply holds up to 10 blocks, fewer than the 20 ablocksreply may hold, so keep a drawer to 10 blocks if your buttons return it.lines, when given, replace the lines your app added to the price. They apply only while the price is not yet fixed (see the guest step guide). Once the guest has started to pay, BookingNinja ignores them.reservation_idreplaces the reservation, when the action swapped it.nullclears it.guest_summaryreplaces the summary the guest sees.nullclears it.
To refuse an action, reply 422 with {"errors": {"note": "Write a note."}} for a form field, or {"error": {"code": "invalid_request", "message": "..."}} for anything else. Reply 409 with the code unavailable when an item has gone. Staff see the message. A refusal changes nothing.
Each action that your app answers is written to the booking's history, with the staff member's name, for example "Board Sheep: Swap game by Sam".
A framed page of your own
For something blocks cannot show, an app can ask for a page of its own to open inside the drawer. It is an escape hatch, it is switched off unless BookingNinja enables it, and your app needs the drawer slot too. Ask us before you build one. The reference describes the frame and its token.
Alerts
An alert tells staff that a booking needs a person now: "Game due back in 10 minutes", "Lane 4 needs attention". Your app needs the bookings:alert scope.
{
"title": "Game due back in 10 minutes",
"message": "Catan, table 7",
"level": "warning",
"key": "due-back-res_77be1c"
}
Send it to POST /api/v1/apps/bookings/{ref}/alerts with your token. The reply is 201:
{ "id": "alr_5f3a9c", "delivered": true }
titleis 1 to 60 characters.messageis optional, 200 characters at most.levelisinfo,warningorurgent. It is shown on the alert. It does not change who is told.keyis your own name for the alert, up to 64 characters. The samekeyfor the same booking within 10 minutes is answered with the first alert'sidand nothing else happens. Without akey, the same title and message count as the same alert. Use akeyso a retry never reaches staff twice.
Who is told
BookingNinja never contacts anyone by itself. The alert goes through the venue's own notification triggers, so the venue chooses who is told, and how. Before anyone is told, the venue must create an active trigger on "An app raised an alert", in Notifications, then Triggers, with at least one channel switched on: the bell in the admin, a phone alert, email, a text message, a webhook or Discord.
delivered tells you what happened. It is true only when such a trigger will tell someone about this alert. When it is false, the alert is only recorded on the booking's history. Your app cannot make a venue set up a trigger, so tell venues what to do in your own setup guide.
The scope reaches a venue only when it connects. If you add bookings:alert to your manifest later, each venue has to connect again. After it does, the Apps page tells the venue its staff can be alerted, and where to choose who is told.
Limits
| Limit | Value |
|---|---|
| Alerts for one installation | 30 an hour |
| Alerts for one booking | 6 an hour |
Over a limit, BookingNinja answers 429 with the code rate_limited and a Retry-After header. A repeat of an earlier alert does not count towards the limits.
A booking that is cancelled, or that finished more than 24 hours ago, takes no more alerts. BookingNinja answers 409 with the code booking_closed.
Notes
A note goes in the booking's history, where staff see it as your app's name followed by the note. Your app needs the bookings:write_notes scope.
{ "note": "Game returned with one card missing." }
Send it to POST /api/v1/apps/bookings/{ref}/notes. The reply is 201 with {"created": true}. A note is up to 1,000 characters, and markup is stripped. Every call adds a new note, so sending the same note twice adds it twice.
Events
Events tell your app that something happened. List the ones you want in extension_points.events. BookingNinja sends no others.
| Event | Sent when |
|---|---|
booking.confirmed |
Your app's hold on the booking has become a reservation |
booking.updated |
The booking's party size, date, time, tables or session changed. changed lists which. |
booking.cancelled |
A booking your app had a reservation for was cancelled |
booking.checked_in |
The guest arrived |
booking.completed |
The guest left |
booking.no_show |
The guest did not come |
installation.settings_updated |
The venue saved your app's settings |
installation.uninstalled |
The venue disconnected your app. The only event sent after that. |
Each is a POST /events with a body like this:
{
"event_id": "evt_k3m9x2a7q1",
"type": "booking.updated",
"occurred_at": "2026-12-05T09:12:00Z",
"changed": ["time"],
"context": {
"installation_id": "ins_8f2k4a9b",
"venue": { "id": "ven_41c7d2", "name": "The Games Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
"settings": { "venue": {}, "session": {} },
"booking": {
"ref": "bkg_9d3f6e1a",
"status": "confirmed",
"session": { "id": "ses_5e8a1c", "name": "Saturday play" },
"date": "2026-12-05",
"start": "15:00",
"end": "17:00",
"party_size": 4
}
}
}
The context holds the booking as it was when the event was queued.
Delivery and retries
Delivery is at least once. Reply with any 2xx status and a JSON object, such as {}, within 10 seconds. That is the acknowledgement.
Anything else counts as a failed delivery: a timeout, a 4xx or 5xx status, or a 2xx with an empty body or text that is not a JSON object. BookingNinja then tries again after growing gaps. The gaps, in minutes, are 1, 5, 15, 60, 180, 360, 720, which spreads the attempts over just under a day. After the last gap it gives up on that event.
Because of retries, your app may receive the same event more than once, and a retried event can arrive after a newer one. The event_id is the same on every attempt, and it is also the Idempotency-Key. Keep the ids you have handled and ignore a repeat.
The Recent events list on Build your own app shows the last 50 deliveries from the past seven days, with their status and attempts.