Creates a confirmed booking for a visitor in the current organization. The request must include `visitorEmail`, `visitorName`, `date`, and a 30-minute `timeSlot` between `09:00` and `16:30`. `conversationId` is optional for operators and links the booking to an existing conversation. Widget visitors must provide their own conversation ID. If another confirmed booking already uses the same date and slot, the endpoint returns `409`. Authenticate with an organization API key sent in `X-API-Key` or as a Bearer token and carrying the exact `scheduling:write` scope. API-key access also requires the Automation & API module (`automation_api`). Authorized dashboard sessions remain supported where the route already permits them. The request is isolated to the authenticated organization. Resource and site/project identifiers must belong to that organization; out-of-scope identifiers are not disclosed. The created booking always starts in `confirmed` status. Other stable statuses are `cancelled`, `completed`, and `no_show`. The slot must be in the future, within 09:00–17:00 business hours, and aligned to a 30-minute increment. A confirmed booking at the same organization and absolute instant returns `409`. No idempotency key is accepted. After an ambiguous timeout, list bookings for the conversation or recheck availability before retrying; a successful first request commonly makes the retry return `409`. Organization API keys may omit `conversationId`; visitor bearer callers must provide a conversation they own. Retry behavior: This operation is not idempotent. After an ambiguous timeout, read the resource state before retrying to avoid duplicate work, messages, files, bookings, exports, or events.
/api/scheduling/bookOrganization API key supplied as Authorization: Bearer convor_sk_....
In: header
application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
{
"booking": {
"id": "22222222-2222-4222-8222-222222222222",
"orgId": "33333333-3333-4333-8333-333333333333",
"visitorEmail": "[email protected]",
"visitorName": "Ada Lovelace",
"date": "2030-06-15",
"timeSlot": "10:00",
"timezone": "Europe/Warsaw",
"conversationId": "11111111-1111-4111-8111-111111111111",
"status": "confirmed",
"createdAt": "2030-05-01T08:00:00.000Z",
"updatedAt": "2030-05-01T08:00:00.000Z"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}{
"error": {
"code": "string",
"message": "string",
"fields": {
"property1": "string",
"property2": "string"
},
"details": {},
"correlationId": "string"
}
}curl --request POST \
'https://api.convor.io/api/scheduling/book' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer convor_sk_...' \
--header 'Content-Type: application/json' \
--data '{
"visitorEmail": "[email protected]",
"visitorName": "Ada Lovelace",
"date": "2030-06-15",
"timeSlot": "10:00",
"timezone": "Europe/Warsaw",
"conversationId": "11111111-1111-4111-8111-111111111111"
}'const response = await fetch("https://api.convor.io/api/scheduling/book", {
method: "POST",
headers: {
"Accept": "application/json",
"Authorization": "Bearer convor_sk_...",
"Content-Type": "application/json"
},
body: JSON.stringify({
"visitorEmail": "[email protected]",
"visitorName": "Ada Lovelace",
"date": "2030-06-15",
"timeSlot": "10:00",
"timezone": "Europe/Warsaw",
"conversationId": "11111111-1111-4111-8111-111111111111"
}),
});
const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
? null
: contentType.includes("json")
? await response.json()
: contentType.startsWith("text/")
? await response.text()
: await response.blob();
if (!response.ok) {
const message = typeof data === "object" && data !== null
&& "error" in data && typeof data.error === "object"
&& data.error !== null && "message" in data.error
? String(data.error.message)
: "Convor API request failed (" + response.status + ")";
throw new Error(message);
}
console.log(data);Was this page helpful?
Cancel a booking
Cancels one booking in the current organization by setting its status to `cancelled`. Use this when a visitor or operator needs to release a confirmed time slot. Widget visitors may cancel only bookings linked to their own conversation; operators may cancel any organization booking. The booking must belong to the current organization. Missing bookings return `404`, and bookings that are already cancelled return `422`. Authenticate with an organization API key sent in `X-API-Key` or as a Bearer token and carrying the exact `scheduling:write` scope. API-key access also requires the Automation & API module (`automation_api`). Authorized dashboard sessions remain supported where the route already permits them. The request is isolated to the authenticated organization. Resource and site/project identifiers must belong to that organization; out-of-scope identifiers are not disclosed. The operation releases the confirmed slot and clears any reminder claim. Visitor bearer callers may cancel only bookings linked to their own conversation. Retry behavior: Cancellation is a terminal transition from `confirmed` to `cancelled`. A repeated request or an attempt to cancel `completed` or `no_show` returns `422`; after an ambiguous timeout, read the booking list before retrying.
Get available time slots for a date
Returns available 30-minute booking slots for one date in the current organization. Slots run from 09:00 through 16:30, exclude past times in the requested timezone, and exclude already confirmed bookings. The `timezone` query accepts IANA zones and fixed offsets. When omitted, `UTC` is used. Authenticate with an organization API key sent in `X-API-Key` or as a Bearer token and carrying the exact `scheduling:read` scope. API-key access also requires the Automation & API module (`automation_api`). Authorized dashboard sessions remain supported where the route already permits them. The request is isolated to the authenticated organization. Resource and site/project identifiers must belong to that organization; out-of-scope identifiers are not disclosed. `date` is required in `YYYY-MM-DD` form. `timezone` accepts an IANA zone or fixed UTC offset and defaults to `UTC`. The response lists future 30-minute slots from 09:00 through 16:30 in the requested timezone, excluding confirmed bookings that resolve to the same absolute instant. Retry behavior: This read-only operation is safe to retry.