Page types
A page type is the kind of page you send. There are 13; each has its own fields, and the person's answer comes back in that type's result shape. You set it in the spec's page field and list them with GET /v1/page-types. A page only collects the answer: it never books, reserves or buys anything. You do that yourself afterwards, and tell the person it is done only once you have.
| Page type | Type | Answers? | What it is |
|---|---|---|---|
| Restaurants | restaurant_picker | Yes | Let the person choose one restaurant and, if it lists table times, one time. The page records the choice; it does not reserve a table. The result is { restaurantId, time? }. |
| Time slots | time_slots | Yes | Let the person pick one or several time slots across one or more days (tables, appointments, meetings). The page records the choice; it does not reserve the slot. |
| Forms | form | Yes | A short general form. Use it only when no more specific page type fits. Do not ask for payment card details, passwords or other credentials, or identity-document numbers: such fields are rejected. |
| Products | product | Yes | Show one product with photos, price and options. The person picks options and a quantity; the page records the choice and buys nothing. The result is { productId, variantId?, selections?, quantity }. |
| Product lists | product_list | Yes | Show 2-24 products as a grid or list; the person picks one or several; the page records the picks and buys nothing. The result is { items: [{ productId, quantity }] }. |
| Cart review | checkout | Yes | Cart review: the person reviews and edits the items, picks shipping if offered and enters delivery details. No payment is taken on the page. The result is the (possibly edited) cart and details; any purchase is up to you. |
| Tables | table | Yes (display-only when select is omitted) | Rows and columns of data: orders, availability, price comparisons. Display-only unless select is set. |
| Charts | chart | No (display-only) | Show data as charts: trends, comparisons, shares and headline numbers. Every chart gets a generated text summary and a data table for screen readers. Display only: the page asks for no answer. |
| Artifacts | artifact | No (display-only) | A document to read: a plan, summary, draft, notes or instructions written in markdown. Display only: the page asks for no answer. |
| Itineraries | itinerary | Yes (display-only when readOnly is true) | A day-by-day plan you propose (a trip, a weekend, a wedding day, a conference, a night out) for the person to approve or change. Result is { decision: "approve" } or { decision: "changes", items?: [{ itemId, note? }], note? }. |
| Hotels | hotel_picker | Yes | Let the person choose one hotel for a stay. The page records the choice; it does not book or hold a room. The result is { hotelId }. |
| Dates | date_range | Yes | A calendar for choosing one date or a date range (stays, appointments, deadlines). |
| Flights | flight_picker | Yes | Let the person choose one flight itinerary. The page records the choice; it does not book or hold a seat. |
Using pages well
- When to send a page: the person must compare options with several details (flights, times, prices), choose from more than three choices, or fill in more than two fields. For yes/no, a single free-text answer, or a choice between two or three short words, ask in chat.
- One page per decision. If the decision changes, cancel the old page and create a new one.
- Title: what the person is deciding, in their words, under 60 characters ("Pick your flight to Lisbon"). Add a one-sentence
descriptiononly for context the options do not already show. - Options: give each a short, stable
idthat means something to you (tap-1234,thai-place, not1,2,3): the answer contains only ids. Offer 8 options or fewer, best first. - Sending the link: send the URL with one short sentence that says what it is for, and stop. Do not list the options again in chat.
- When the answer arrives: confirm the choice by its name, not its id. A page only collects the answer: it never books, orders or pays. Say what you will do, not that it is done, and say it is done only after your own action succeeds.
- Errors:
invalid_specnames each wrong field: fix them and create the page again.payment_required,spend_cap_reachedorburst_limitmean page creation is paused: do not retry; ask in chat and tell the person once that you cannot send pages right now.