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.
| 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.
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}/canceland/reschedule. To find the booking, look the customer up withGET /customers?phone=...and readGET /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 /availabilitywithoutstaff_idonly returns staff who do it, so offer names from the slots. - Prices for one person.
price_centson 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.