Chatfuel Public API Overview

The Chatfuel Public API lets your own software work with Chatfuel bots: read and update contacts, send WhatsApp, Instagram, Facebook, TikTok and website chat messages, manage bookings and the catalog, and build flows and AI automations. It is a GraphQL API at https://panel.chatfuel.com/graphql, built for developers who connect Chatfuel to a CRM, an internal tool or their own product.

What the Public API covers

The Public API is a stable, documented part of the same GraphQL API the Chatfuel dashboard uses. Only fields that are explicitly published belong to it, so internal changes to the dashboard never break your integration. Published fields change only by adding new fields or arguments; anything that is going away is deprecated first and keeps working until a stated date, as described in versioning and deprecation.

The Public API is organized around a bot. Everything you can read or change belongs to one bot and is reached from the bot(id:) query or from a mutation that takes a botID:

• bots and account data: the bot, its settings, the current account
• team and roles: virtual users, teammates and invites
• contacts: contacts, attributes, assignees, notes, sales stages, CSV import and export
• messaging: conversations and messages on every channel, WhatsApp templates
• flows: flows, blocks, keyword rules and test chats
• AI automations: Fuely AI settings, automations and broadcasts
• bookings and catalog: bookings, specialists, products and services
• channels: WhatsApp, Instagram, Facebook, TikTok and website widget settings
• files and tasks: file upload and long-running tasks

How access works: personal token and virtual users

The Public API accepts two kinds of tokens, and they are not equal.

The personal API token belongs to you, a real Chatfuel user. In the dashboard it is called the CLI token. It acts with your own permissions in every bot you are a member of. Use it for a small set of account-level operations: creating and removing virtual users, managing teammates, renaming or deleting bots, connecting channels and working with workspaces.

A virtual user is an API-only account that you create inside one bot with the Editor or Agent role. It has its own token, cannot sign in to the dashboard and cannot see anything outside its bot. Use virtual user tokens for all day-to-day work: contacts, messages, flows, automations, bookings. Every example in these docs uses a virtual user token unless it says Personal token only.

Create one virtual user per integration, or one per customer of your product. If a token leaks, you remove a single virtual user instead of losing access to your whole account. Authentication compares the two tokens in detail, and virtual users explains roles and limits.

What a request looks like

Every call is an HTTP POST with a JSON body to https://panel.chatfuel.com/graphql. The token goes in the Authorization header with the Bearer scheme:

curl https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query Bot($id: BotID!) { bot(id: $id) { id title timezone } }","variables":{"id":"'"$BOT_ID"'"}}'

The response is standard GraphQL JSON with data and, when something fails, errors. Making requests covers pagination, subscriptions and file uploads, and errors lists the error codes.

What you need to start

To start with the Public API you need:

• A Chatfuel account with the Admin role in the bot, because only bot admins can create virtual users.
• A server or backend job to make the calls. The Public API is for server-to-server use: browsers on other domains are blocked by CORS, and tokens must never be shipped to a browser or mobile app.
• About ten minutes for the quickstart, which takes you from no token to your first API call.

Limits at a glance

• Rate limit: 25 operations per second per account. Each virtual user has its own limit.
• Virtual users: up to 20 per bot.
• Page size: up to 500 items per page for contacts, conversations and keyword rules.
• Tokens: shown once when created and valid for 10 years unless revoked.

Common issues

Requests from a web page fail with a CORS error

The Public API accepts browser requests only from the Chatfuel dashboard. Call it from your server and keep the token there; your web page talks to your server.

Can I use the API key from Settings → API?

The API key in a bot's settings is a different, older key for the broadcasting and contact import endpoints. The Public API accepts only the personal API token (CLI token) and virtual user tokens.