Bookings and Catalog API Reference
Manage bookings, specialists, products and services through the Public API: read the calendar, create and update appointments, and sync Google Calendar.
Last updated on
The bookings and catalog part of the Chatfuel Public API covers what Fuely AI sells and schedules: products and services in the catalog, specialists with their working hours, and the bookings in the calendar. An integration can mirror bookings to another system, create appointments from a website or CRM, and keep the catalog in sync with a store. Reading works for Agent virtual users; creating and changing anything needs Editor.
How to read bookings
type Bot {
# Agent. Bookings in the time range.
bookingsV2(startTime: Time!, endTime: Time!): [BookingBase!]!
bookingV2(id: BookingID!): BookingBase!
# A booking contact without a chat, found by phone number.
inlineContact(phoneNumber: String!): BookingInlineContact
}query Week($botID: BotID!) {
bot(id: $botID) {
bookingsV2(startTime: "2026-10-12T00:00:00Z", endTime: "2026-10-19T00:00:00Z") {
id
startTime
endTime
status # Pending, Reschedule, Confirmed, Canceled, Attended, NoShow
service { ... on GoodsService { id title } }
specialist { id }
}
}
}Times are RFC 3339 timestamps. A booking is linked either to an existing contact (contactID) or to an inline contact with a name and phone number, for people who booked without chatting with the bot.
How to create and change bookings
type Mutation {
# Editor. Errors: BookingStartTimeRequired, BookingEndTimeRequired, BookingInvalidDuration,
# BookingEndTimeBeforeStartTime, BookingContactPlatformNotAllowed
bookingCreateV2(botID: BotID!, req: BookingInput!): BookingBase!
bookingUpdateV2(botID: BotID!, id: BookingID!, req: BookingUpdateInput!): BookingBase!
# Editor. Confirm, cancel or mark as attended or no-show.
bookingStatusResolveV2(botID: BotID!, bookingID: BookingID!, status: BookingStatus!): BookingBase!
bookingDeleteV2(botID: BotID!, id: BookingID!): BookingBase!
# Editor. Errors: BookingInlineContactNoteTooLong
bookingInlineContactSetNote(id: InlineContactID!, note: String): BookingInlineContact!
}
input BookingInput {
contactID: ContactID # an existing contact, or
inlineContact: BookingInlineContactInput # { name, phoneNumber, note, countryCode }
serviceID: GoodsItemID
specialistID: SpecialistID
startTime: Time!
endTime: Time!
}mutation Book($botID: BotID!, $serviceID: GoodsItemID!, $specialistID: SpecialistID!) {
bookingCreateV2(
botID: $botID
req: {
inlineContact: { name: "Ana Souza", phoneNumber: "+5511999990000", countryCode: "BR" }
serviceID: $serviceID
specialistID: $specialistID
startTime: "2026-10-14T13:00:00Z"
endTime: "2026-10-14T14:00:00Z"
}
) { id status }
}Booking subscriptions
type Subscription {
# Agent.
bookingAdded(botID: BotID!): Booking!
bookingUpdated(botID: BotID!): Booking!
bookingDeleted(botID: BotID!): BookingID!
}How to manage specialists
Specialists are the people or resources a booking is made with, each with a profile, a weekly schedule and the services they provide. Read them with bot.specialists and bot.specialist(id:) (Agent).
type Mutation {
# Editor. Errors: SpecialistNameNotUnique, SpecialistFirstNameRequired, SpecialistFirstNameTooLong, …
specialistCreate(botID: BotID!, info: SpecialistInfoInput!): Bot!
specialistUpdate(botID: BotID!, specialistID: SpecialistID!, info: SpecialistInfoInput!): Specialist!
specialistDelete(botID: BotID!, specialistID: SpecialistID!): Bot!
}
input SpecialistInfoInput {
profile: SpecialistProfileInput!
schedule: SpecialistScheduleInput!
goodsServices: [GoodsItemID!]!
}How to connect a specialist's Google Calendar
A specialist's Google Calendar keeps their availability in sync with the rest of their schedule. The calendar owner connects it through a link, so nobody shares Google credentials:
type Mutation {
# Editor. Creates a link the calendar owner opens to connect their Google Calendar.
specialistCreateGoogleCalendarConnectionLink(botID: BotID!, specialistID: SpecialistID!): SpecialistGoogleCalendarLink!
specialistDeleteGoogleCalendarConnectionLink(botID: BotID!, specialistID: SpecialistID!): Bot!
# Editor. Starts a sync; follow its progress with taskUpdated. Errors: SpecialistDoesNotExist
specialistStartGoogleCalendarSync(botID: BotID!, specialistID: SpecialistID!): Task!
specialistDisconnectGoogleCalendar(botID: BotID!, specialistID: SpecialistID!, googleCalendarID: GoogleCalendarID!): Specialist!
}bot.availableGoogleCalendars, the calendars of your own Google account, is Personal token only. Files and tasks describes Task and taskUpdated.
How to manage products and services
The catalog holds products and services that Fuely AI can recommend and book. Read it with bot.goodsCatalog, bot.goodsProduct(id:) and bot.goodsService(id:) (Agent).
type Mutation {
# Editor. Errors: GoodsItemsTooMuchForBot, GoodsItemTitleRequired, GoodsItemTitleNotUnique,
# GoodsItemTitleTooShort, GoodsItemTitleTooLong, GoodsItemDescriptionTooLong, …
goodsProductCreate(botID: BotID!, product: GoodsProductInput!): Bot!
goodsProductUpdate(botID: BotID!, itemID: GoodsItemID!, product: GoodsProductInput!): GoodsProduct!
goodsProductDelete(botID: BotID!, itemID: GoodsItemID!): Bot!
goodsServiceCreate(botID: BotID!, service: GoodsServiceInput!): Bot!
goodsServiceUpdate(botID: BotID!, itemID: GoodsItemID!, service: GoodsServiceInput!): GoodsService!
goodsServiceDelete(botID: BotID!, itemID: GoodsItemID!): Bot!
}
input GoodsProductInput {
title: String!
description: String!
price: GoodsItemPriceInput # { amount: "199.90", currency: … }
images: [FileID!]!
isAvailable: Boolean!
}
input GoodsServiceInput {
title: String!
description: String!
price: GoodsItemPriceInput
images: [FileID!]!
durationSeconds: Int!
isAvailable: Boolean!
}Upload product images first, as described in making requests, and pass their file IDs in images. Titles must be unique within the catalog. Update mutations replace the whole item, so send every field.
Common issues
"BookingContactPlatformNotAllowed"
The contact is on a channel bookings don't support. Use a contact from a supported channel, or book with an inlineContact by phone number.
"GoodsItemTitleNotUnique"
Another product or service already has this title. Titles are compared within the whole catalog of the bot.
"NotEnoughPermissions" when an Agent creates a booking
Agents can read bookings, specialists and the catalog but can't change them. Use an Editor virtual user.