Appointment Scheduling API

Convor's scheduling API is a booking API for 30-minute appointments. It is separate from Settings → Scheduling, which configures SLA business hours and links to operator/chatbot schedule controls, and separate from each operator's Weekly Availability used by routing.

The appointment booking window is currently fixed server-side: slots start every 30 minutes from 09:00 through 16:30 in the requested timezone.

Booking lifecycle

A booking stores the visitor name and email, local date and time slot, timezone, an optional conversation link for organization API-key callers, and its lifecycle status.

Supported statuses are:

• confirmed
• cancelled
• completed
• no_show

A confirmed booking reserves one absolute time instant for the organization. Conflicting confirmed bookings return 409.

Check availability

GET /api/scheduling/availability?date=2030-06-15&timezone=Europe%2FWarsaw

date must use YYYY-MM-DD. timezone accepts an IANA timezone such as Europe/Warsaw or a fixed UTC offset and defaults to UTC.

The response returns future, unclaimed 30-minute start times:

{
  "date": "2030-06-15",
  "timezone": "Europe/Warsaw",
  "data": ["09:00", "09:30", "10:00"]
}

Create a booking

POST /api/scheduling/book

{
  "visitorEmail": "[email protected]",
  "visitorName": "Ada Lovelace",
  "date": "2030-06-15",
  "timeSlot": "10:00",
  "timezone": "Europe/Warsaw",
  "conversationId": "11111111-1111-4111-8111-111111111111"
}

The slot must be in the future, use a 30-minute increment, and start between 09:00 and 16:30.

Organization API keys may omit conversationId. Visitor bearer callers must provide a conversation they own. Booking creation is not idempotent; after an ambiguous timeout, check availability or list the conversation's bookings before retrying.

Read bookings

List all lifecycle states linked to one conversation:

GET /api/scheduling/bookings?conversationId=11111111-1111-4111-8111-111111111111

The response is not paginated. Visitor bearer callers can read only bookings linked to their own conversation.

Operators can also list confirmed bookings for a day:

GET /api/scheduling/bookings/daily?date=2030-06-15

The daily endpoint is not available to visitor bearer tokens.

Reschedule a booking

POST /api/scheduling/bookings/:id/reschedule

{
  "date": "2030-06-16",
  "timeSlot": "11:30",
  "timezone": "Europe/Warsaw"
}

Rescheduling keeps the booking ID and conversation link and records the previous date/slot. The new slot must satisfy the same time and conflict rules as booking creation.

Record the outcome

Operators can move a confirmed booking to a terminal outcome:

POST /api/scheduling/bookings/:id/outcome

{
  "status": "completed"
}

The accepted outcome values are completed and no_show.

Cancel a booking

DELETE /api/scheduling/bookings/:id

Cancelling a confirmed booking changes its status to cancelled, releases the slot, and clears its reminder claim. An already-cancelled booking returns 422; completed or no-show bookings return 409.

Fixed booking hours

The booking API's 09:00–16:30 start-time window is currently fixed for all organizations. Workspace business hours in Settings → Scheduling do not change appointment availability.

That distinction matters because Convor has three other schedule concepts:

• Workspace business hours: used by SLA policies that count business hours only.
• Operator Weekly Availability: used by routing to determine whether an operator is on shift.
• AI Chatbot operating hours: controls when autonomous replies are allowed for a site.

API reference

See the Scheduling API reference for request and response schemas.