--- title: "Fuely AI and Automations API Reference" description: "Configure Fuely AI through the Public API: Automations and their settings, company knowledge, booking rules and WhatsApp broadcasts." canonical_url: https://chatfuel.com/docs/public-api/ai-automations markdown_url: https://chatfuel.com/docs/public-api/ai-automations.md last_updated: 2026-10-06 lang: en site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Fuely AI and Automations API Reference Configure Fuely AI through the Public API: Automations and their settings, company knowledge, booking rules and WhatsApp broadcasts. 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](https://chatfuel.com/docs/ai-features/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 [#how-to-read-automations] ```graphql 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! } ``` ```graphql 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 [#how-to-change-automations] ```graphql 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 [#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 automation * `setInheritFrom`: the ID of an automation to inherit the value from * `setInheritFromScope`: 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: ```graphql 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 [#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**: ```graphql 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](https://chatfuel.com/docs/public-api/bookings-and-catalog). ## WhatsApp broadcasts [#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](https://chatfuel.com/docs/public-api/messaging) (**Editor**): ```graphql 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](https://chatfuel.com/docs/public-api/flows): for example, choose recipients with `whatsAppOneTimeNotificationUpdateSegment`, then send with `whatsAppOneTimeNotificationSend`. ## Subscription [#subscription] ```graphql 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](https://chatfuel.com/docs/public-api/flows). ## Common issues [#common-issues] ### "FuelyAutomationBeingEdited" [#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 [#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" [#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.