跳到主要内容

预订请求

你已发布地图的访客可以就地图上的某个地点向你的商家发送请求：在场所订位、参观房源、到门店预约、在站点接送。请求会送达你组织在 booking.kaleidr.com 上 Kaleidr Booking 的收件箱，如果你选择也会通过电子邮件送达，还可以通过 webhook 送达你自己的系统。你在收件箱中回复。

请求只是请求，不是已确认的预订。不会预留、保留或支付任何东西：由你的商家通过电子邮件或惯常方式确认。

开启请求​

  1. 在 Kaleidr Booking 中打开设置、常规，开启接收请求。关闭期间，任何访客都无法向你的组织发送请求，请求按钮也不会出现。
  2. 在 Kaleidr Studio 中为一个集合添加请求操作：打开集合，在卡片和筛选、地点操作中添加请求。它的标签就是访客看到的按钮；每个套件都有自己的默认标签：
集合类型默认标签访客请求
门店Request an Appointment预约、自取或回答一个问题
房源Schedule a Tour现场或视频看房，或更多信息
场所Reserve预订或回答一个问题
站点Request Pickup接送、预订购或通知
  1. 发布一张显示该集合的地图。之后，它的地点卡片、地点布局以及 Ask Kaleidr 回答中的地点都会带有该按钮。
  • 每个集合一个请求操作。 添加后，集合中的每个地点都会开启请求。新的场所集合以 Reserve 开始，新的站点集合以 Request Pickup 开始。
  • 车辆和自定义集合不接受请求。
  • 聊天中的地点。 在 Studio 中，地图的请求设置里的接受任意地点的请求还能让访客就 Kaleidr AI 在回答中提到的地点发送请求，例如你酒店附近的餐厅。它默认关闭。这类请求以名称和地址标识地点。只有在 Kaleidr 自有的地址数据中找到该地址时，它才带有地图位置。
  • Kaleidr AI 可以填写表单，但绝不发送。 当访客说“订一张 7 点的四人桌”时，Ask Kaleidr 面板会用访客所说的内容准备表单，并显示查看并发送。访客检查后补充自己的信息再发送。Kaleidr AI 从不会看到访客的姓名、电子邮件或电话。

表单​

访客会在地图上方看到表单：集合套件的字段、姓名、电子邮件和可选的电话、留言，以及同意声明。在必填字段填写完毕并勾选同意框之前，发送请求一直不可用。发送后，访客会看到请求已发送和类似 K-7XQ2MD 的参考编号。关于表单本身，请参阅请求表单。

在 Kaleidr Booking 中，设置、请求表单为每个套件提供一个标签页。你可以为每个字段选择是否显示、是否必填及其标签，还可以添加最多五个自己的问题。旁边的预览会按访客将看到的样子显示表单。

套件标准字段
门店请求事由、日期、时段、物品
房源请求事由、现场或视频看房、最多三个日期、时段、资金方式
场所请求事由、日期、时间、人数（1 到 50）、晚数（1 到 60）
站点请求事由、上车点、目的地、日期、时间、人数（1 到 20）、物品

上车点和目的地是访客输入的文字。在实时布局上，如果站点集合的请求操作允许访客选择它们，则会加入通过地址搜索或点按地图找到的两个点。这是访客选择交给你处理的位置。

防机器人。 未登录 Kaleidr 的访客在发送请求前需要通过一次简短的人机验证。

收件箱​

Kaleidr Booking 中的请求是一个看板，包含新请求、已接受、已完成和已拒绝几列。拖动卡片可更改其状态，也可以使用其移至菜单。显示垃圾请求会显示标记为垃圾的请求。可按地图、地点、套件和日期筛选，或按参考编号、姓名、电子邮件或地点搜索。

打开一个请求，可以查看访客的信息和回答、访客给予的同意、地图上的地点以及请求的历史。在这里可以：

操作作用
接受、拒绝、标记为已完成、标记为垃圾请求、重新打开更改状态。新请求可以接受、拒绝或标记为垃圾；已接受的请求可以标记为已完成或拒绝；已拒绝或垃圾请求可以重新打开。已完成为最终状态。
回复通过电子邮件将你的回复发给访客。访客的答复会发到你自己的电子邮件地址。
添加备注只有你的团队能看到的备注，绝不会发送。
分配给将请求交给你组织的某位成员。
清除请求人数据删除你组织中来自该电子邮件地址的所有请求。参阅保留与清除。

谁能做什么取决于你组织中的角色：所有者、管理员、成员和查看者可以阅读请求；所有者、管理员和成员可以更改、回复和分配请求；所有者和管理员管理设置、表单、webhook 和通知，删除和清除请求，并将其导出为 CSV。

电子邮件。 在设置、通知中，通过邮件通知新请求会在请求到达时向在团队中开启通知的成员发送邮件。邮件写明地点和请求类型并链接到该请求，但不包含访客的任何信息。发送回执会把带参考编号的副本发给访客。

测试请求。 你自己从 Studio 发送的请求会标记为测试，不计入你套餐的限制。

表单中的同意声明为：“我同意 你的商家 使用这些信息来回复我的请求。Kaleidr 代表 你的商家 处理这些信息。” 其中 你的商家 会替换为你的商家名称：即设置、常规中的商家名称，否则为你组织的名称。将隐私政策链接设置为你自己政策的 https:// 地址后，声明会链接到它。同意框初始未勾选，未勾选的请求会被拒绝。每个请求都会保存访客所同意声明的版本及同意时间。

保留与清除​

  • 请求保留时长：请求在这段时间内没有任何活动就会被删除；默认 365 天，可设为 30 到 730 天。标记为垃圾的请求会在 30 天后删除。
  • 清除请求人数据会删除你组织中某个电子邮件地址的所有请求，以及与之相关的已发送邮件。当有人要求你删除其数据时使用。
  • 删除请求会同时删除与其相关的已发送邮件。
  • 当某人删除其 Kaleidr 账户时， 其请求会在所有组织中被删除。
  • 当你的组织被删除时， 其请求也会一并删除。

Webhook​

webhook 会在每个请求事件发生时将其发送到你的地址，这样你的预订系统、CRM 或表格自动化就能据此处理。在 Kaleidr Booking 的设置、Webhook 中添加。Webhook 适用于 Pro 和 Enterprise。

  • 地址必须是端口 443 上的 https， 并且其名称解析到的每个地址都必须是公网地址。任何其他端口或私有地址在保存时都会被拒绝，并在每次投递时再次检查。
  • 密钥只显示一次， 即在你添加 webhook 时。轮换密钥会生成新密钥；旧密钥会继续签名 24 小时，方便你切换。
  • 发送测试会发送一个 webhook.test 事件。
事件发送时机
request.created访客发送请求。
request.status_changed请求的状态发生变化。data.from_status 包含之前的状态。
request.replied有人回复了访客。data.reply 包含 { body, created_at }。
webhook.test你选择了发送测试。

每次投递都是一个带 JSON 正文和以下请求头的 POST：

请求头值
Kaleidr-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>
Kaleidr-Event-Id事件的 ID，每次重试都相同。用它来忽略重复。
Kaleidr-Event-Type事件，与上表相同。
Kaleidr-Delivery-Attempt1 到 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": "…"
    }
  }
}

对于聊天中某个地点的请求，如果在 Kaleidr 自有的地址数据中找不到其地址，则 place.lat 和 place.lng 为 null。

验证签名​

在解析之前验证原始正文，并拒绝超过五分钟的时间戳。轮换期间，请求头会带有第二个用旧密钥签名的 v1=；两者均可接受。

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)

用以下向量测试你的代码：

输入值
密钥whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
t1761091200
正文{"id":"8a1c2b9e-0000-4000-8000-000000000001","type":"webhook.test"}
v13e55a2f93ac990282b95fd9140f8290ffaddc5d41969831e4234b164d613bd72

投递与重试​

  • 在 10 秒内以任意 2xx 状态应答。 不会跟随重定向。
  • 至少一次。 投递失败后会在 1 分钟、5 分钟、30 分钟、2 小时、6 小时和 24 小时后重试：约 32 小时内共七次尝试。同一事件可能到达两次；请忽略你已见过的 Kaleidr-Event-Id。
  • 正文是发送时的请求， 因此重试会带上其最新状态。在此期间被清除的请求不会发送。
  • 连续十次投递的所有尝试都失败时，webhook 会被关闭。 重新开启会重置计数。
  • 每个 webhook 下的投递记录列出最近 30 天的尝试及其状态、响应代码和耗时，不含正文。重试会重新发送失败的投递。

限制​

限制FreeProEnterprise
每月请求数501,000按你的协议设定
Webhook无5按你的协议设定

一个月指你组织的计费周期。测试请求不计入。达到限制后，新请求在下一个周期之前都会被拒绝；如果地点有电话或链接，表单会改为显示它们。

相关内容​