chatfuel-lab/wizard / content/modules/core/skill
skill
VerifiedChatfuel GraphQL API — core
The foundation every chatfuel-* skill builds on: transport & auth, the mandatory backend proxy, pagination, cross-domain gotchas, the bundled schema, shared operations and the validator. Domain surfaces (live chat, contacts, deals, automations, flow builder, preview chat, Coworker, knowledge base, bookings, team management) live in the sibling ../chatfuel-* skills.
Required inputs
Ask the user for these before writing code:
- Base URL — the Chatfuel dashboard origin. Production:
https://panel.chatfuel.com. Derive endpoints from it:- HTTP:
POST {base}/graphql - WebSocket:
wss://{host}/graphql(subprotocolgraphql-transport-ws) - REST (uploads etc.):
{base}/api/...
- HTTP:
- API token — a Chatfuel dashboard auth token. The account owner generates it at
https://panel.chatfuel.com/integration/auth/tokenand pastes it in; rotation means generating a new one there. Treat it as a server-side secret. - botID — the Chatfuel project ("bot") id. Discoverable via the
BotsListoperation (examples/operations.graphql) once the token works.
Architecture requirement: a backend proxy
Browsers on foreign origins cannot call the API directly — production CORS allows only https://panel.chatfuel.com. Any browser-based UI must route GraphQL through the integrator's own backend, which also keeps the token off the browser. Read references/cors-proxy.md before designing anything browser-facing. Server-to-server calls need no proxy.
One consequence is worth stating on its own, because every fence in this codebase exists because of it: there is one token, it holds the whole account, and it does not distinguish the deployment's customers from each other. A proxy serving more than one of them is the only thing standing between one customer's request and another customer's bot, so it decides which bot a caller may name — it never asks the caller.
Mental model
- Hierarchy: UserAccount → Workspace → Bot ("project") → ContactScope (channel: WhatsApp number / Instagram / Facebook page / TikTok / web widget) → Contact → Conversation.
- Almost everything is scoped by
botID— you read data by traversingbot(id:)andcurrentUser, not via per-entity root queries. - Platforms:
widget | facebook | instagram | whatsapp | tiktok. Message types, send mutations, and some fields are per-platform — always branch onConversation.platform/__typename. Conversation.idIS the contact id (server-side alias). EveryconversationIDargument takes the contact's id.- Real-time = GraphQL subscriptions over one lazy WebSocket (
graphql-transport-ws). Lists update via batched Add/Update/Remove edge events that the client must merge and re-sort itself. Exception: the flow builder has no subscriptions — reconcile from mutation results. - Two separate automation surfaces, don't confuse them. Automations = how the AI behaves, configured per scope (channel + entry point): Bot → FuelyAutomation (one base per scope, plus custom ones) → FuelySetting (the chatfuel-automations skill). Flows = scripted logic on a canvas: Bot → Flow → Block (canvas node) → BlockElement ("plugin" card) → buttons/handles → connections, strongly typed per plugin, no JSON configs (the chatfuel-flow-builder skill).
- Permissions per bot role (
Admin | Editor | Agent | Custom):Inboxgates live chat,Peoplecontacts,ContactsAssignedToOthers/ContactsUnassignedvisibility. Check with theMyBotRoleoperation (examples/operations.graphql).
Files in this skill
| File | What's inside |
|---|---|
references/schema.graphql | Full SDL (introspection is disabled in production — this is your only schema source; grep it for exact fields) |
references/possible-types.json | interface/union → concrete types map (needed by normalized caches, e.g. Apollo possibleTypes) |
references/transport-auth.md | Endpoints, auth header, WS connection, reconnect strategy, error envelope, rate limits, token lifecycle |
references/cors-proxy.md | Why a proxy is mandatory + requirements spec for building it |
references/pagination.md | Cursor pagination semantics (typed cursors, direction quirks) |
references/files-tasks.md | REST file uploads, File entity, async Task tracking patterns |
references/misc.md | Uncovered surfaces map: widget config, WhatsApp templates, keywords, broadcasts, platform connections, Meta Ads, IG publishing |
references/platform-links.md | Platform links: one-shot connection / access-refresh URLs for WhatsApp, Instagram, TikTok, Facebook pages — lifecycle, replace-on-create, the URL as credential, redirects, disconnecting a channel, the public side that is not for you |
references/gotchas.md | Read this before writing any operation — cross-domain sharp edges |
examples/operations.graphql | Shared operations every module needs: CurrentUser, BotsList (bot discovery), MyBotRole (permissions), FileGet/FileStartDownload, BotChannels, BotDisconnectContactScope, BotPlatformLinks + the platform-link create/revoke mutations |
scripts/validate-operations.mjs | Validates this skill's and every sibling chatfuel-* skill's examples against the schema — extend it to validate your own operations before shipping |
Working rules
- Never introspect production — it's disabled. Use
references/schema.graphql. - Validate every operation you write against the bundled schema (reuse
scripts/validate-operations.mjs) before running it against the live API. - Read
references/gotchas.mdfirst; it prevents the recurring classes of bugs (missing__typename, wrong per-platform field names, names this schema does not publish, fake pagination). - Copy operations from the relevant skill's
examples/operations.graphqlas the starting point — they encode the known quirks. 4a. A generated app refuses a document it does not ship. In an app scaffolded by@chatfuel/wizard, the proxy checks every request against the documents exported from the namespaces insrc/operationDocs.tsand answers403 OperationNotInRegistryfor anything else — a field added to an existing operation included, since that is a different document. So an operation of your own has to be exported from a namespace that barrel imports, not merely written somewhere the client can reach. - When output must go to a browser UI, design the proxy first (
references/cors-proxy.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |