Skip to Content
Developers

An assistant that books

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.

WhatYou need
KeyWrite key A write key, on the server, never in the chat window.
EndpointsGET /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.
AssistantYour 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.

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 returnsThe assistant
booked: trueGives the time and the code, and says a confirmation mail is on its way.
slot_takenSays someone booked the time a moment ago and calls findFreeTimes again.
invalid_requestAsks 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_reachedThe customer holds as many open bookings as the shop allows. Offers to pass them to the shop.
not_allowedThe shop blocked this customer from booking online. Passes them to the shop without saying why.
bookings_pausedThe 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.

On this page