The Chatfuel API

The mental model behind the GraphQL API a generated app talks to — the hierarchy every operation traverses, the two automation surfaces that are not the same thing, and why the schema ships as a file.

The supergraph has thirteen root query fields, so you reach almost everything by traversing bot(id:) and currentUser rather than by asking for an entity by its own name.

The hierarchy

Level	What it is	How you reach it
`UserAccount`	The Chatfuel login the token belongs to.	`currentUser`
`Workspace`	The billing container. It holds bots and carries a `botsLimit`.	`currentUser.workspaces`, `currentUser.workspace(id:)`
`Bot`	One Chatfuel project. Almost every field in the schema hangs off it, and almost every argument list opens with a `botID`.	`bot(id: BotID!)`, `Workspace.bots`
`ContactScope`	One connected channel. The interface carries an id and nothing else; five types implement it — web widget, WhatsApp phone, Instagram account, TikTok account, Facebook page.	`bot.contactScopes`
`Contact`	A person inside one scope.	`bot.contactsConnection`
`Conversation`	The thread with that contact.	`bot.conversation(conversationID:)`, `Contact.conversation`

Conversation.id is the contact's id: the backend's primary key for a conversation is Conversation.ContactID, exposed as an alias on id. Every conversationID argument in the schema takes a contact id, and there is no separate conversation identity to look up.

Automations and Flows are two different surfaces

	Automations	Flows
What it configures	How the AI behaves.	Scripted logic on a canvas.
The chain	`Bot → FuelyAutomation → FuelySetting`	`Bot → Flow → Block → BlockElement`
Scoping	One base automation per scope, plus custom ones. A scope is a channel and an entry point together — `InstagramPostComments`, `WhatsAppClickFromAds`, `FacebookDirectMessages` — and a setting can inherit from another automation in the same bot.	Per flow. Blocks carry canvas positions and are joined by `Connection`s; a flow names its `startingPointBlock` and its `entryPoints`.
Typing	`FuelySetting` is an interface with one concrete type per setting.	Strongly typed per plugin. There are no JSON configs.
Real time	`fuelyAutomationUpdated(botID:)`.	None. The `Subscription` type carries no flow or block field, so you reconcile from mutation results.

Everything sendable branches on platform

enum Platform {
  widget
  facebook
  instagram
  whatsapp
  tiktok
}

Message types, send mutations and some fields exist per platform, so you branch on Conversation.platform or on __typename before you read a message. Field names are disambiguated per platform for the same reason — see the traps.

One endpoint per environment, not per account

Production is https://panel.chatfuel.com/graphql for every account; the botID inside the operation selects the project. The addresses, the header, the socket and the rate limit are on transport and auth.

The schema is a file, not an introspection query

Introspection is disabled in production, so the bundled SDL is the schema. The SDK carries it at schema/schema.graphql — a copy of the Chatfuel dashboard's own schema with billing, Albato, A/B-experiment and debug surfaces dropped, along with every field, argument and union member that referred to a dropped name. scripts/refresh-schema.ts reproduces that copy and writes the source commit into the file's header. Codegen reads that file, the operation validator builds from it, and a byte-identical copy ships inside the chatfuel-core skill your coding agent reads, so grepping any of the three answers the same question.

The rest of this section

Page	What it holds
Transport and auth	The three endpoints, how the token travels on each, what the token is and what it may do, the WebSocket client's behaviour, and 25 requests per second.
Errors	The envelope, the `DefinedErrorCode` family, and the four rules that catch people.
Pagination	Relay cursors with per-connection scalars, the direction flip on message history, and the connections that take pagination arguments and ignore them.
Files and tasks	REST upload then `FileID`, the `File` lifecycle, and `Task` progress tracking.
Traps	The cross-domain sharp edges, in full.