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_blocks with the slots you fill: gantt_bar, list_row and drawer.
  • staff_actions set 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 {}.

json
{
  "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, call POST /api/v1/apps/blocks/refresh with the refs 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:

json
{
  "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." }
  ]
}
  • id names the button and comes back as action_id. It must be unique across the whole drawer: if two buttons share one, the first wins.
  • style is default, primary or danger.
  • confirm makes BookingNinja ask staff to confirm, with your wording, first.
  • input is collection to open the catalogue picker first, or fields to 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:

json
{
  "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.items holds 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 checklist block may carry an action_id. Ticking it presses that action with input.values set 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 no action_id is for display only.
  • Payments are never touched. An action cannot take or refund money.

Your reply says what to change:

json
{
  "message": "Note added.",
  "drawer": [
    { "type": "text", "text": "Box was damp." }
  ]
}
  • message is a short toast for staff, 200 characters at most.
  • drawer replaces the drawer's blocks. A drawer in an action reply holds up to 10 blocks, fewer than the 20 a blocks reply 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_id replaces the reservation, when the action swapped it. null clears it.
  • guest_summary replaces the summary the guest sees. null clears 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.

json
{
  "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:

json
{ "id": "alr_5f3a9c", "delivered": true }
  • title is 1 to 60 characters. message is optional, 200 characters at most. level is info, warning or urgent. It is shown on the alert. It does not change who is told.
  • key is your own name for the alert, up to 64 characters. The same key for the same booking within 10 minutes is answered with the first alert's id and nothing else happens. Without a key, the same title and message count as the same alert. Use a key so 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.

json
{ "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:

json
{
  "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.