Skip to main content

Booking requests

A visitor of one of your published maps can send your business a request about a place on it: a reservation at a venue, a tour of a listing, an appointment at a store, a pickup at a stop. The request reaches your organization's inbox in Kaleidr Booking at booking.kaleidr.com, by email if you choose, and your own systems through webhooks. You answer it from the inbox.

A request is a request, not a booking. Nothing is reserved, held or paid for: your business confirms it, by email or as it usually does.

Turn requests on​

  1. In Kaleidr Booking, open Settings, General and turn on Accept Requests. While it is off, no visitor can send your organization a request, and the request buttons do not appear.
  2. In Kaleidr Studio, add a request action to a collection: open the collection, Card & Filters, Place Actions, and add Request. Its label is the button visitors see; each kit starts with its own:
Collection typeDefault labelThe visitor asks for
StoresRequest an AppointmentAn appointment, a pickup, or an answer to a question
ListingsSchedule a TourA tour in person or by video, or more information
VenuesReserveA reservation, a booking, or an answer to a question
StopsRequest PickupA pickup, a preorder, or a notice
  1. Publish a map that shows the collection. Its place cards, its place layouts and the places in its Ask Kaleidr answers then carry the button.
  • One request action a collection. Adding it turns requests on for every place of the collection. A new Venues collection starts with Reserve, and a new Stops collection with Request Pickup.
  • Vehicles and Custom collections take no requests.
  • Places in the chat. A map's Requests setting in Studio, Accept Requests for Any Place, also lets visitors send a request about a place Kaleidr AI names in its answers, such as a restaurant near your hotel. It is off by default. Such a request names the place by its name and address. It carries a map position only when the address was found in Kaleidr's own address data.
  • Kaleidr AI can fill in a form, never send it. Asked "book a table for four at 7", the Ask Kaleidr panel prepares the form with what the visitor said and shows Review and Send. The visitor reviews it, adds their details and sends it. Kaleidr AI never sees a visitor's name, email or phone.

The form​

A visitor sees the form over the map: the fields of the collection's kit, their name, email and an optional phone, a message, and the consent line. Send Request stays disabled until the required fields are filled and the consent box is checked. After sending, the visitor sees Request Sent and a reference such as K-7XQ2MD. For the form itself, see The request form.

In Kaleidr Booking, Settings, Request Forms has a tab for each kit. For each field you choose whether it is shown, whether it is required and its label, and you can add up to five questions of your own. The preview beside it shows the form as visitors will see it.

KitStandard fields
StoresWhat the request is for, date, time of day, items
ListingsWhat the request is for, tour in person or by video, up to three dates, time of day, financing
VenuesWhat the request is for, date, time, party size (1 to 50), nights (1 to 60)
StopsWhat the request is for, pickup, destination, date, time, party size (1 to 20), items

Pickup and destination are text the visitor types. On the live layout, a Stops collection whose request action lets visitors pick them adds the two points, found by an address search or a tap on the map. They are what the visitor chose for you to act on.

Bots. A visitor who is not signed in to Kaleidr passes a short human check before the request is sent.

The inbox​

Requests in Kaleidr Booking is a board with the columns New, Accepted, Done and Declined. Drag a card to change its status, or use its Move To menu. Show Spam shows the requests marked as spam. Filter by map, place, kit and date, or search by reference, name, email or place.

Open a request to see the visitor's details and answers, the consent they gave, the place on a map and the request's history. From there:

ActionWhat it does
Accept, Decline, Mark Done, Mark as Spam, ReopenChanges the status. A new request can be accepted, declined or marked as spam; an accepted one can be marked done or declined; a declined or spam request can be reopened. Done is final.
ReplySends your reply to the visitor by email. Their answer comes to your own email address.
Add NoteA note for your team only. It is never sent.
Assign ToGives the request to a member of your organization.
Erase RequesterDeletes every request from that email address in your organization. See Retention and erasure.

Who can do what follows the roles of your organization: owners, admins, members and viewers can read requests; owners, admins and members can change, answer and assign them; owners and admins manage settings, forms, webhooks and notifications, delete and erase requests, and export them as CSV.

Email. Under Settings, Notifications, Email New Requests emails the members turned on under Team when a request arrives. The email names the place and the kind of request and links to it; it carries none of the visitor's details. Send Receipts emails the visitor a copy with the reference.

Test requests. A request you send yourself from Studio is marked Test, and does not count toward your plan's limit.

The form's consent line reads: "I agree that your business may use these details to answer my request. Kaleidr processes them on your business's behalf.", with your business name in place of your business: the Business Name under Settings, General, else your organization's name. Set Privacy Policy Link to an https:// address of your own policy, and the line links to it. The box starts unchecked, and a request is refused without it. Each request keeps the version of the line the visitor agreed to and when.

Retention and erasure​

  • Keep Requests For deletes a request after that long without activity: 365 days unless you change it, from 30 to 730 days. A request marked as spam is deleted after 30 days.
  • Erase Requester deletes every request of one email address in your organization, with the emails sent about them. Use it when a person asks you to delete their data.
  • Deleting a request deletes it and the emails sent about it.
  • When a person deletes their Kaleidr account, their requests are deleted in every organization.
  • When your organization is deleted, its requests go with it.

Webhooks​

A webhook sends each request event to an address of yours as it happens, so your reservation system, CRM or spreadsheet automation can act on it. Add one in Kaleidr Booking under Settings, Webhooks. Webhooks are on Pro and Enterprise.

  • The address must be https on port 443, and every address its name resolves to must be public. Any other port, or a private address, is refused when you save it and again on every delivery.
  • The secret is shown once, when you add the webhook. Rotate Secret issues a new one; the old one keeps signing for 24 hours, so you can switch over.
  • Send Test sends a webhook.test event.
EventSent when
request.createdA visitor sends a request.
request.status_changedA request's status changes. data.from_status holds the previous one.
request.repliedSomeone replies to the visitor. data.reply holds { body, created_at }.
webhook.testYou choose Send Test.

Each delivery is a POST with a JSON body and these headers:

HeaderValue
Kaleidr-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
Kaleidr-Event-IdThe event's id, the same on every retry. Use it to ignore a repeat.
Kaleidr-Event-TypeThe event, as in the table above.
Kaleidr-Delivery-Attempt1 to 7.
{
  "id": "8a1c2b9e-0000-4000-8000-000000000001",
  "type": "request.created",
  "api_version": "2026-10-22",
  "created_at": "2026-10-22T15:04:05Z",
  "org_id": "…",
  "data": {
    "request": {
      "id": "…",
      "ref": "K-7XQ2MD",
      "kit": "venues",
      "status": "new",
      "place": { "name": "Sample Venue", "line": "…", "lat": 40.7411, "lng": -73.9897 },
      "requester": { "name": "…", "email": "…", "phone": null, "locale": "en", "signed_in": false },
      "fields": { "kind": "reservation", "date": "2026-10-30", "time": "19:00", "party_size": 4 },
      "message": "…"
    }
  }
}

A request about a place in the chat whose address was not found in Kaleidr's own address data has place.lat and place.lng set to null.

Verify the signature​

Verify the raw body before you parse it, and refuse a timestamp more than five minutes old. During a rotation, the header carries a second v1=, signed with the previous secret; accept either.

import hashlib, hmac, time

def verify(header: str, secret: str, body: bytes, tolerance: int = 300) -> bool:
    parts = [p.split("=", 1) for p in header.split(",")]
    t = next((v for k, v in parts if k == "t"), "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)

Test your code with this vector:

InputValue
secretwhsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
t1761091200
body{"id":"8a1c2b9e-0000-4000-8000-000000000001","type":"webhook.test"}
v13e55a2f93ac990282b95fd9140f8290ffaddc5d41969831e4234b164d613bd72

Delivery and retries​

  • Answer with any 2xx status within 10 seconds. Redirects are not followed.
  • At least once. A delivery that fails is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours: seven attempts over about 32 hours. The same event can arrive twice; ignore a Kaleidr-Event-Id you have seen.
  • The body is the request as it is when sent, so a retry carries its latest state. A request erased in the meantime is not sent.
  • Ten deliveries in a row that fail every attempt turn the webhook off. Turning it on again resets the count.
  • Deliveries under each webhook lists the last 30 days of attempts with their status, response code and time, without the bodies. Retry sends a failed one again.

Limits​

LimitFreeProEnterprise
Requests a month501,000Set in your agreement
WebhooksNone5Set in your agreement

A month is your organization's billing period. Test requests do not count. At the limit, new requests are refused until the next period, and the form shows the place's phone or link instead when it has one.