wittle labs

REFERENCE

Booking lifecycle

Every booking takes two steps so a customer always approves a clear summary first, and the status an assistant reports is always the one the business’s system gave.

Prepare, then confirm

  1. get_availability returns options, each with an opaque, signed option_id. Pass it back unchanged; it can’t be edited or forged.
  2. prepare_booking takes the option, the customer’s details and answers to the business’s questions. It runs the safety check and the business’s rules and returns a summary, an expected_outcome and a preparation_id that expires in 15 minutes. Nothing is booked.
  3. Show the summary. Only after the customer approves, call confirm_booking with the preparation_id and an idempotency_key.

expected_outcome tells the assistant what confirming will do: AUTO_CONFIRM (booked immediately), REQUEST (sent for the business to accept) or HANDOFF (call to book).

Statuses

StatusMeaningWhat the assistant should do
CONFIRMEDThe business's scheduler booked it.Tell the customer; keep the booking_id.
PENDING_PROVIDERSent as a request; the business accepts or declines.Nothing more to do. Don't confirm again; check get_booking_status later.
HANDOFF_REQUIREDThe business's rules say this can't be booked online.Give the customer the business's phone number.
FAILEDThe booking couldn't be completed (e.g. the time was taken).Offer other times or the business's phone number.
OUTCOME_UNKNOWNThe scheduler didn't answer in time; Wittle is checking.Don't book again. Wittle resolves it by lookup, usually within 15 minutes.
EXPIREDThe prepared booking wasn't confirmed within 15 minutes.Prepare again.

Each result also carries a plain next_step sentence written for the assistant.

Idempotency: confirming twice never books twice

  • The same idempotency_key always returns the same booking.
  • A second confirm of a preparation that already has a booking returns that booking, whatever key is used.
  • Wittle records the attempt before it contacts the business’s scheduler, so a crash or timeout can never create a second booking. An uncertain result becomes OUTCOME_UNKNOWN and is resolved by looking the booking up, never by booking again.

Safety

If the problem description suggests danger (a gas smell, a carbon monoxide alarm, sparking, smoke, or similar for the trade), Wittle returns emergency guidance and the business’s emergency number instead of a booking. Wittle is not an emergency service.

Privacy

  • A person only ever sees their own bookings; get_booking_status for anyone else’s says “unknown booking”.
  • The business receives the booking details the customer gives, and nothing else about them.
  • Customers never see a business’s other appointments, only open times.