Reserve Time Slot
reserve_slotReserve a time slot on an active configured calendar. Returns a pending_offer reservation and tries to send a 6-digit confirmation code to the customer's email or phone. The reservation expires in 15 minutes if not confirmed. Idempotent: re-using the same idempotency_key returns the original reservation and sends no code. If a send could not be confirmed, confirmation.delivered is false and not_sent_reason says whether a code may still arrive. At a business that takes a deposit for agent bookings, pass the offer_id from get_quote (without it the answer is quote_required); no code is sent and the result's payment block carries the amount to pay instead. If the result includes customer_notice, show it to the customer word for word.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"slug": "<slug>",
"window_start": "<window_start>",
"window_end": "<window_end>",
"customer_contact": "<customer_contact>",
"idempotency_key": "<idempotency_key>"
},
"name": "reserve_slot"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Business slug identifier | |
| agent_id | No | Optional agent identifier | |
| offer_id | No | Optional id of a signed get_quote offer to redeem against this reservation. Omit for a business with no exact-priced service — authentication is a capability upgrade here, never a toll. | |
| window_end | Yes | Slot end (Unix seconds, an absolute instant) — the matching get_availability slot's `end`; see window_start. | |
| window_start | Yes | Slot start (Unix seconds, an absolute instant). Take it from a get_availability slot: that response carries the business's `timezone`, so request a wide availability window there and filter the returned slots locally rather than guessing the zone. | |
| idempotency_key | Yes | Unique key for idempotent reservation | |
| customer_contact | Yes | How to reach the customer. MUST include at least one of email or phone — the confirmation code is delivered there, and a hold nobody can confirm is unreachable from both sides. Email is used when both are present. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | Reservation state — 'pending_offer' on a fresh hold; a replay returns the existing row's state | |
| payment | No | Always present. required:false — confirm with the code (confirmation.method 'otp'). required:true — the customer pays amount_cents (currency) to confirm; balance_due_cents is paid at the visit. | |
| expires_at | Yes | ISO-8601. When this hold lapses if it is not confirmed (by code, or by payment when payment.required) | |
| confirmation | Yes | ||
| reservation_id | Yes | ||
| booking_details | No | For configured calendars: present these fixed booking details to the customer before confirming their code. No owner approval is required. | |
| customer_notice | No | A sentence for the customer. When present, show it to them word for word. | |
| idempotent_replay | No | Present and true when this idempotency_key already had a reservation; no new code was sent | |
| booking_authorization | No | Present this summary and booking_details to the customer and obtain explicit agreement before passing its reference to confirm_booking. |