# An assistant that books

Source: https://developers.weerom.com/docs/use-cases/assistant

> A chat or phone assistant that looks up free times and makes the booking, from your server with a write key.

**For** a shop that wants a chatbot on its site or in WhatsApp, or a voice assistant on its phone line, that answers "can I come in Saturday morning?" with a real time and books it.

The assistant runs on your server. When the customer asks for a time, it calls `GET /availability` and offers what is free. When the customer says yes and gives their name, phone and email, it calls `POST /bookings`. WeerOm books under the shop's rules and sends the customer the shop's confirmation mail, with the link to move or cancel.

| What | You need |
| --- | --- |
| Key | **Write key** A write key, on the server, never in the chat window. |
| Endpoints | `GET /shop`, `GET /services`, `GET /staff`, `GET /availability`, `POST /bookings`. With a lookup of the customer: `GET /customers` and `GET /bookings`, which `POST /bookings/{id}/cancel` and `/reschedule` can act on. |
| Assistant | Your chat or voice model, with tools it may call. Your own code connects them to the functions below. |

## Why a write key and not a public key

A public key books under a visitor's limits, counted per address. Every request from your server comes from the server's address, so a public key would stop after 10 booking requests in an hour for all your customers together. A write key runs under its own 120 requests a minute. Keep it on the server: it also reads every customer.

Leave `as` out, or send `"as": "customer"`. The assistant books as a customer, so the shop's lead time, its paused switch, its cap on open bookings and its blocked customers all apply, as on its own booking form. `"as": "staff"` would skip them. An assistant that strangers talk to should not.

## The tools

Give the assistant two tools: one that finds free times and one that books. Each is a small function on your server.

```js title="tools.js"
const BASE = "https://api.weerom.com/v1";

async function weerom(path, { body, idempotencyKey } = {}) {
  const headers = { Authorization: `Bearer ${process.env.WEEROM_KEY}` };
  if (body) headers["Content-Type"] = "application/json";
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
  const response = await fetch(`${BASE}${path}`, {
    body: body ? JSON.stringify(body) : undefined,
    headers,
    method: body ? "POST" : "GET",
  });
  const json = await response.json();
  return { ok: response.ok, json };
}

const shop = (await weerom("/shop")).json;
const services = (await weerom("/services?active=true")).json.data;
const staff = (await weerom("/staff?active=true")).json.data;
const clock = new Intl.DateTimeFormat("nl-BE", {
  dateStyle: "full",
  timeStyle: "short",
  timeZone: shop.time_zone,
});

/** Tool: free times for a service on a day, as text the model can read. */
export async function findFreeTimes({ serviceName, date, staffName }) {
  const service = services.find((s) => s.name.toLowerCase() === serviceName.toLowerCase());
  if (!service) return { error: `No service called ${serviceName}. Offer: ${services.map((s) => s.name).join(", ")}.` };
  const person = staffName ? staff.find((p) => p.name === staffName) : null;

  const query = new URLSearchParams({ date, days: "1", service_id: service.id });
  if (person) query.set("staff_id", person.id);
  const { ok, json } = await weerom(`/availability?${query}`);
  if (!ok) return { error: json.error.message };

  return {
    slots: json.data.map((slot) => ({
      label: `${clock.format(new Date(slot.starts_at))} with ${staff.find((p) => p.id === slot.staff_id)?.name}`,
      service_id: slot.service_id,
      staff_id: slot.staff_id,
      starts_at: slot.starts_at,
    })),
  };
}

/** Tool: book one slot from findFreeTimes for the person the assistant talks to. */
export async function bookSlot({ slot, name, phone, email, conversationId }) {
  const { ok, json } = await weerom("/bookings", {
    body: {
      customer: { email, name, phone },
      service_id: slot.service_id,
      staff_id: slot.staff_id,
      starts_at: slot.starts_at,
    },
    // One booking per conversation and time, however often the model retries.
    idempotencyKey: `${conversationId}-${slot.starts_at}-${slot.staff_id}`,
  });
  if (ok) return { booked: true, code: json.code, starts_at: json.starts_at };
  return { booked: false, code: json.error.code, message: json.error.message };
}
```

`date` is a day in the shop's own calendar, such as `2026-11-30`. Tell the model today's date on the shop's clock, so "Saturday" becomes the right day.

## What the assistant says back

| `bookSlot` returns | The assistant |
| --- | --- |
| `booked: true` | Gives the time and the `code`, and says a confirmation mail is on its way. |
| `slot_taken` | Says someone booked the time a moment ago and calls `findFreeTimes` again. |
| `invalid_request` | Asks for what `message` names. "First and last name are required" means it needs a last name. "Email is required" means it needs an email. |
| `limit_reached` | The customer holds as many open bookings as the shop allows. Offers to pass them to the shop. |
| `not_allowed` | The shop blocked this customer from booking online. Passes them to the shop without saying why. |
| `bookings_paused` | The shop takes no online bookings right now. Gives the shop's phone number. |

## How often

A conversation makes a few requests: one or two `GET /availability` calls and one `POST /bookings`. The services, staff and shop are read once at start. One key serves about 40 conversations a minute at 3 requests each before it reaches 120. No polling: the assistant asks when the customer asks.

## Limits

- **Who is on the other end.** The API trusts the name, phone and email the assistant sends. Anyone can give someone else's number. The shop's confirmation mail goes to the email given, so a wrong email means a confirmation nobody reads.
- **Moving and cancelling.** A write key can cancel and move with `POST /bookings/{id}/cancel` and `/reschedule`. To find the booking, look the customer up with `GET /customers?phone=...` and read `GET /bookings?customer_id=...&status=confirmed`. Proving the person on the line is that customer is yours to build. Until then, point them to the manage link in their confirmation mail.
- **The staff list does not say who does which service.** `GET /availability` without `staff_id` only returns staff who do it, so offer names from the slots.
- **Prices for one person.** `price_cents` on a service is the list price. A deal or a loyalty card can lower it. The booking that comes back has the price the customer will pay.
