Referencia de la API de reservas y catálogo
Gestiona reservas, especialistas, productos y servicios con la Public API: lee el calendario, crea y actualiza citas y sincroniza Google Calendar.
Última actualización
La parte de reservas y catálogo de la Public API de Chatfuel cubre lo que Fuely AI vende y agenda: los productos y servicios del catálogo, los especialistas con su horario de trabajo y las reservas del calendario. Una integración puede replicar las reservas en otro sistema, crear citas desde un sitio web o un CRM y mantener el catálogo sincronizado con una tienda. La lectura funciona para usuarios virtuales Agent; para crear o cambiar cualquier cosa se necesita Editor.
Cómo leer las reservas
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 }
}
}
}Las horas son marcas de tiempo RFC 3339. Una reserva está vinculada a un contacto existente (contactID) o a un contacto inline con nombre y número de teléfono, para las personas que reservaron sin chatear con el bot.
Cómo crear y cambiar reservas
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 }
}Suscripciones de reservas
type Subscription {
# Agent.
bookingAdded(botID: BotID!): Booking!
bookingUpdated(botID: BotID!): Booking!
bookingDeleted(botID: BotID!): BookingID!
}Cómo gestionar especialistas
Los especialistas son las personas o los recursos con los que se hace una reserva, cada uno con un perfil, un horario semanal y los servicios que ofrece. Léelos con bot.specialists y 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!]!
}Cómo conectar el Google Calendar de un especialista
El Google Calendar de un especialista mantiene su disponibilidad sincronizada con el resto de su agenda. El dueño del calendario lo conecta mediante un enlace, así nadie comparte credenciales de Google:
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, que devuelve los calendarios de tu propia cuenta de Google, es Solo token personal. Archivos y tareas describe Task y taskUpdated.
Cómo gestionar productos y servicios
El catálogo contiene los productos y servicios que Fuely AI puede recomendar y reservar. Léelo con bot.goodsCatalog, bot.goodsProduct(id:) y 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!
}Primero sube las imágenes de los productos, como se describe en cómo hacer solicitudes, y pasa sus IDs de archivo en images. Los títulos deben ser únicos dentro del catálogo. Las mutaciones de actualización reemplazan el elemento completo, así que envía todos los campos.
Problemas comunes
"BookingContactPlatformNotAllowed"
El contacto está en un canal que no admite reservas. Usa un contacto de un canal compatible o reserva con un inlineContact por número de teléfono.
"GoodsItemTitleNotUnique"
Otro producto o servicio ya tiene este título. Los títulos se comparan dentro de todo el catálogo del bot.
"NotEnoughPermissions" cuando un Agent crea una reserva
Un usuario virtual Agent puede leer reservas, especialistas y el catálogo, pero no puede cambiarlos. Usa un usuario virtual Editor.
Referencia de la API de Fuely AI y Automations
Configura Fuely AI con la Public API: Automations y sus ajustes, conocimiento de la empresa, reglas de reserva y broadcasts de WhatsApp.
Referencia de la API de canales
Lee los canales conectados de un bot y gestiona WhatsApp, Instagram, Facebook, TikTok y el widget web. Conectar canales requiere el token personal.