Developers

Table page blocks

How your app shows live blocks and buttons on the page a table's QR code opens, what it is told about the table and the guests there, and how presses, caching and failures work.

Every table at a venue can carry a QR code. When the venue builds a table page, scanning the code opens it: the table's name, who is seated there, a button into ordering, a way to ask for help, and blocks from apps. Your app can be one of them. A board game library can show the game reserved for the party at the table, a few staff picks, and buttons such as "We're playing this" or "Teach us the rules".

Unlike website blocks, a table page block is about one table right now. BookingNinja asks your app while the guest's page loads, tells it which table and, when the booking seated there uses your app, which booking, and shows the answer to whoever is holding the code.

Declare the blocks

Table page blocks are listed in the manifest under extension_points, in table_blocks. A declaration has the same shape as a website block's, without surfaces:

json
{
  "extension_points": {
    "table_blocks": [
      {
        "key": "tonights_game",
        "label": "Tonight's game",
        "description": "The game reserved for the table, staff picks and buttons to ask for help.",
        "icon": "dice",
        "settings": [
          { "key": "picks", "type": "number", "label": "How many staff picks", "default": 3, "min": 1, "max": 6 }
        ]
      }
    ]
  }
}

An app may declare up to 10 table page blocks. key is unique within table_blocks and may repeat a website block's key. settings are the fields the venue fills in for the copy it places, exactly as for website blocks. kind is content (the default) or widget; see the end of this guide.

The consent screen shows the venue "Show its own blocks and buttons on your table QR page". The venue places the block in its table page editor, where it sees a live preview.

The request

BookingNinja calls POST table-blocks at {base_url}/table-blocks, signed like every other call. The timeout is 3 seconds: a guest is waiting for the page.

json
{
  "context": {
    "installation_id": "ins_8f2a6c1d",
    "venue": { "id": "ven_4b1e9d", "name": "The Dice Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
    "settings": { "venue": { "library_id": "lib_main" }, "session": {} },
    "table": { "ref": "tbl_k3x9q2", "name": "Table 4", "floor": "Upstairs" },
    "booking": {
      "ref": "bkg_9f3c1a7e5b2d8046",
      "status": "checked_in",
      "session": { "id": "ses_2c7d", "name": "Evening" },
      "date": "2026-12-05",
      "start": "18:00",
      "end": "20:00",
      "party_size": 4,
      "tables": ["Table 4"],
      "guest": { "name": "Sam" },
      "hold_id": null,
      "reservation_id": "res_51"
    },
    "guest": { "signed_in": false }
  },
  "block": "tonights_game",
  "settings": { "picks": 3 },
  "preview": false
}
  • table is the table whose code was scanned. Its ref is your app's own opaque ref for that table, stable for the table's life and different for every app. Its floor is the floor or area name, or null.
  • booking is the booking seated at the table now (its start minus 15 minutes to its end, an arrived party first), and only when that booking uses your app. Its ref is the one your app already knows it by, so you can find the game you reserved. A booking that does not use your app is never sent.
  • guest says whether the person looking is signed in to the venue's booking site. With customers:read a signed-in guest also carries ref, the same customer ref your app sees in events and on the customer card.
  • preview is true while the venue looks at the block in its editor. The table and booking are then samples (the refs tbl_preview and bkg_preview), nothing is kept and buttons cannot be pressed.

Privacy: anyone at the table can see it

The page is open to whoever holds the code: a party at the table, a friend they send the link to, the next party once they have gone. Treat everything your blocks show as said out loud at the table.

  • The seated booking's guest carries the first name only, and only when the venue granted guests:read or bookings:read_all. Its email and phone are never sent on these calls.
  • Show the first name at most. Never show contact details, payment details, other bookings or anything about the guest you hold from elsewhere.
  • A signed-in guest's ref tells you who is looking, not who booked. Show them their own things only if you are sure they are the seated guest's.

The answer

json
{
  "blocks": [
    { "type": "text", "text": "Tonight's game", "style": "heading" },
    { "type": "notice", "title": "Catan is waiting for you", "text": "Sam, it is reserved for Table 4. Ask at the counter.", "tone": "info" },
    { "type": "details", "rows": [ { "label": "Players", "value": "3-4" }, { "label": "Play time", "value": "90 min" } ] },
    { "type": "actions", "actions": [
      { "id": "playing_this", "label": "We're playing this", "style": "primary" },
      { "id": "teach_rules", "label": "Teach us the rules", "fields": [
        { "key": "note", "type": "textarea", "label": "Anything we should know?", "max_length": 200 }
      ] }
    ] },
    { "type": "cards", "layout": "grid", "cards": [
      { "title": "Splendor", "meta": "Staff pick", "image_url": "https://games.example.com/img/splendor.png", "alt": "The box of Splendor" }
    ] }
  ],
  "valid_for_seconds": 30
}

blocks is up to 20 blocks, drawn in order in the page's own fonts and colours. The table page takes these block types:

Block type Notes
text A heading or a paragraph.
notice A titled note in one of the five tones.
hero A wide picture.
gallery Up to twelve pictures.
steps A short timeline or list of steps.
details Label and value rows.
faq Questions and answers.
table Rows and columns.
meter A bar, such as play time used.
stat One figure, large.
links Up to six HTTPS links.
divider A line.
cards A row or list of cards with pictures.
button A link styled as a button.
image_list Items from your synced catalogue by item_id, with their pictures.
tags Small labels.
actions Buttons the guest presses (below).

Other types are left out. An empty list shows nothing.

Caching and failure

BookingNinja keeps your answer for valid_for_seconds: between 0 and 300 seconds, 30 if you leave it out. A copy is kept for each block, its settings, the table, the seated booking (when it uses your app), whether the guest is signed in, and who they are (when you are told). While it is fresh it is shown without asking you. Once it is older, the next guest to open the page waits for a new answer; several phones at one table opening the page together make one call.

  • If your app fails, times out or answers out of contract, the last copy is shown, marked out of date. With none the block is left out and the rest of the page shows as normal. Your app is not asked about that copy again for 15 seconds, even when a last copy is being shown, so a failing app is not called on every page view.
  • An app the circuit breaker has paused is not called; its last copies are shown.

Buttons

An actions block on the table page is the guest kind. It holds up to four buttons, and an answer may hold up to three such blocks. Each button has an id (unique across the whole answer), a label, an optional style (default, primary or danger), an optional confirm sentence the guest agrees to first, and optional fields: up to four form fields of the types text, textarea, select, number and toggle. A guest button has no intent.

When a guest presses one, BookingNinja checks that the button is in the copy that guest was last shown for that block and table, checks the answers against the button's fields, and calls POST table-actions within 5 seconds. While a press of the same button at the same table is being sent, a second press is turned away straight away with "That is already being sent. Give it a moment." (nothing is sent to you for it), so you never see two at once; a retried press carries the same Idempotency-Key, so answer it with what you answered the first time.

json
{
  "context": {
    "installation_id": "ins_8f2a6c1d",
    "venue": { "id": "ven_4b1e9d", "name": "The Dice Cafe", "timezone": "Europe/London", "currency": "GBP", "locale": "en-GB" },
    "settings": { "venue": {}, "session": {} },
    "table": { "ref": "tbl_k3x9q2", "name": "Table 4", "floor": null },
    "guest": { "signed_in": false }
  },
  "block": "tonights_game",
  "settings": { "picks": 3 },
  "action_id": "teach_rules",
  "input": { "values": { "note": "We've never played before" } }
}

Answer with the new blocks, which replace the copy that guest and table see at once, and a short message the guest sees as a toast, with a tone (success if you leave it out):

json
{
  "blocks": [
    { "type": "notice", "text": "Someone is on their way to teach you the rules.", "tone": "success" }
  ],
  "message": "Someone is on their way to teach you the rules.",
  "tone": "success"
}

To refuse, reply 422 with {"errors": {"note": "Keep it short."}} for the form's fields, or an error with a message; 409 unavailable when what was asked for has gone. The message is shown to the guest. A press never takes a payment and never changes the booking: if your app needs staff to act, tell them yourself, for example with an alert on a booking that uses your app.

Widgets

A table page block may instead be a widget, a page of your own framed on the table page, declared with a widget object exactly as for website widgets. BookingNinja must have switched widgets on. It frames {url}?token=<token>, where the token's claims are those of a website widget token plus table (the table's ref) and booking (the seated booking's ref when it uses your app, else null), and surface is always table_page. It is signed with its own key, the lowercase hex of HMAC-SHA256 of bookingninja-table-widget-v1 with your signing secret, so a website widget token never passes for a table one. Check the signature, iss, aud, surface and exp. Anyone at the table can read the token: it is not a login.