Fuely AI and Automations API Reference
Configure Fuely AI through the Public API: Automations and their settings, company knowledge, booking rules and WhatsApp broadcasts.
Last updated on
Fuely AI is the assistant that answers a bot's contacts, and Automations decide where and how it answers. Through the Public API an integration can read and change Automations and their settings, fill in the company knowledge Fuely AI uses, set booking rules and create WhatsApp broadcasts. Reading works for Agent virtual users; every change needs Editor.
The API uses the same model as Fuely AI → Automations in the dashboard, described in Automations: the Main bot (scope All), one base automation per source and up to 30 custom automations per source that supports them.
How to read Automations
type Bot {
# Agent. All automations, or those of one scope.
fuelyAutomations(scope: FuelyAutomationScope): [FuelyAutomation!]!
fuelyAutomation(id: FuelyAutomationID!): FuelyAutomation!
# Agent. Conversion events Fuely AI can send to Meta.
availableMetaConversionEventNames: FuelyAvailableMetaConversionEventNames!
}query Automations($botID: BotID!) {
bot(id: $botID) {
fuelyAutomations {
id
scope # All, WhatsAppDirectMessages, InstagramPostComments, …
isBase # true for Main bot and base automations
name # null for base automations
enabled
settings {
__typename
inheritsFrom { id scope }
... on FuelySettingIncomingMessages { howToReply messagePrompt }
}
}
}
}The scopes are All (Main bot); WhatsAppDirectMessages, WhatsAppClickFromAds, WhatsAppClickFromPosts; InstagramDirectMessages, InstagramPostComments, InstagramAdComments, InstagramStoryReplies, InstagramIgMeLinks, InstagramClickFromAds; FacebookDirectMessages, FacebookPostComments, FacebookMMeLinks, FacebookClickFromAds; TikTokDirectMessages, TikTokPostComments, TikTokClickFromAds; and WebWidgetDirectMessage.
How to change Automations
type Mutation {
# Editor. Custom automation, only for scopes that support targeting; up to 30 per scope.
# Errors: FuelyAutomationNameInvalid, FuelyAutomationScopeInvalid, FuelyAutomationScopeLimitReached
fuelyAutomationCreate(botID: BotID!, scope: FuelyAutomationScope!, name: String!): FuelyAutomation!
# Editor. Custom automations only (FuelyAutomationNotRenamable, FuelyAutomationNotDeletable for base ones).
fuelyAutomationSetName(botID: BotID!, id: FuelyAutomationID!, name: String!): FuelyAutomation!
fuelyAutomationDelete(botID: BotID!, id: FuelyAutomationID!): Bot!
# Editor. Turning Main bot off switches off all AI replies.
fuelyAutomationSetEnabled(botID: BotID!, id: FuelyAutomationID!, enabled: Boolean!): FuelyAutomation!
# Editor. Changes one setting; see below.
fuelyAutomationUpdateSetting(botID: BotID!, id: FuelyAutomationID!, update: FuelySettingUpdateInput!): FuelyAutomation!
# Editor. Writes settings onto base automations and creates custom automations in one call.
fuelyAutomationApplyTemplate(botID: BotID!, template: FuelyAutomationTemplateInput!): Bot!
}Names are 1 to 200 characters. Changes to one bot's Automations are applied one at a time; if another change is in progress, the call fails with FuelyAutomationBeingEdited and can be retried.
How to update a setting
fuelyAutomationUpdateSetting changes exactly one setting per call. FuelySettingUpdateInput has one field per setting: messageDelays, whenAIReplies, catalogImages, incomingMessages, bookingRules, switchToHuman, followUps, collectContactInfo, plus the targeting settings keywords, listOfPosts, listOfAds, listOfStories, refLinks, publicReply, privateReply and sendEventsToMeta. Each of them takes one of:
update: an explicit value for this automationsetInheritFrom: the ID of an automation to inherit the value fromsetInheritFromScope: the scope whose base automation to inherit from
Main bot can't inherit. A base automation can inherit only from Main bot; a custom automation, from Main bot or its own base automation. Other combinations fail with FuelyInheritFromInvalid, and a setting that doesn't exist in the scope fails with FuelySettingNotAllowedInScope.
Setting the AI instructions of the WhatsApp base automation, for example:
mutation Instructions($botID: BotID!, $automationID: FuelyAutomationID!) {
fuelyAutomationUpdateSetting(
botID: $botID
id: $automationID
update: {
incomingMessages: {
update: {
howToReply: UsingAI
messagePrompt: "Answer in Portuguese. Offer a free consultation when asked about prices."
}
}
}
) {
id
settings { ... on FuelySettingIncomingMessages { howToReply messagePrompt inheritsFrom { id } } }
}
}messagePrompt holds the Additional instructions and must be 1 to 5,000 characters. The keywords setting accepts up to 50 keywords of up to 50 characters each.
Company knowledge and booking rules
Fuely AI answers from the company information in the bot's Knowledge Base and books appointments by its booking rules. Read them with bot.fuelyConfig { knowledgeBase usage booking } (Agent). Changing them needs Editor:
type Mutation {
fuelyConfigSetCompanyName(botID: BotID!, companyName: String!): Bot!
fuelyConfigSetEmail(botID: BotID!, email: String!): Bot!
fuelyConfigSetPhone(botID: BotID!, phone: String!): Bot!
fuelyConfigSetAddress(botID: BotID!, address: String!): Bot!
fuelyConfigSetWebsite(botID: BotID!, website: String!): Bot!
fuelyConfigSetHowToPay(botID: BotID!, howToPay: String!): Bot!
fuelyConfigSetFAQs(botID: BotID!, faqs: [FuelyKnowledgeBaseFAQInput!]!): Bot!
fuelyConfigSetAdditionalInstructions(botID: BotID!, additionalInstructions: String!): Bot!
fuelyConfigSetBusinessHoursSchedule(botID: BotID!, schedule: FuelyBusinessHoursScheduleUpdateInput!): Bot!
fuelyConfigBookingUpdateAppointments(botID: BotID!, update: FuelyConfigBookingAppointmentsUpdateInput!): Bot!
fuelyConfigBookingUpdateConfirmation(botID: BotID!, enabled: Boolean!, additionalInfo: String): Bot!
fuelyConfigBookingUpdateNotificationChannel(botID: BotID!, channel: FuelyBookingNotificationChannel!): Bot!
fuelyConfigBookingUpdateLocale(botID: BotID!, locale: DashboardLocale!): Bot!
}fuelyConfigSetFAQs replaces the whole list of questions and answers, so send every FAQ you want to keep. Products and services that Fuely AI offers are managed in the bookings and catalog API.
WhatsApp broadcasts
A broadcast sends an approved WhatsApp template to a segment of contacts, once or on a schedule. Read broadcasts with bot.fuelyBroadcasts(first, after) (Agent). Create them with a filled template from the messaging API (Editor):
type Mutation {
# A one-time broadcast, sent when you call whatsAppOneTimeNotificationSend.
fuelyBroadcastWhatsAppOneTimeNotificationCreate(botID: BotID!, filledTemplateID: FilledWhatsAppTemplateID!): FuelyBroadcast!
# A broadcast scheduled for sendTime, which must be in the future (FuelyBroadcastSendTimeCanNotBeInPast).
fuelyBroadcastWhatsAppScheduledMessageCreate(botID: BotID!, filledTemplateID: FilledWhatsAppTemplateID!, sendTime: Time!): FuelyBroadcast!
}Each broadcast is a small flow: settingsBlock holds when and to whom it is sent, and payloadBlock holds the template. Set the audience and timing with the whatsAppOneTimeNotification* and whatsAppScheduledMessage* mutations from the flows API: for example, choose recipients with whatsAppOneTimeNotificationUpdateSegment, then send with whatsAppOneTimeNotificationSend.
Subscription
type Subscription {
# Agent. Fires when any automation of the bot changes.
fuelyAutomationUpdated(botID: BotID!): FuelyAutomation!
}To try an automation without messaging real contacts, start a test chat with previewResponsesStartForFuelyAutomation, described in the flows API.
Common issues
"FuelyAutomationBeingEdited"
Someone else, in the dashboard or through the API, is changing the bot's Automations at the same moment. Wait a second and retry.
"FuelyAutomationScopeInvalid" when creating an automation
Custom automations exist only on comment, ad, story and link sources. Direct-message scopes and All have only their base automation; change its settings instead.
"FuelyInheritFromInvalid"
The inheritance target is not allowed. A base automation can inherit only from Main bot (setInheritFromScope: All), and a custom automation only from Main bot or its own base automation.