--- title: "Chatfuel Public API Overview" description: "The Chatfuel Public API is a GraphQL API for managing bots, contacts, messages and flows from your server, authenticated with virtual user tokens." canonical_url: https://chatfuel.com/docs/public-api/overview markdown_url: https://chatfuel.com/docs/public-api/overview.md last_updated: 2026-10-06 lang: en site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Chatfuel Public API Overview The Chatfuel Public API is a GraphQL API for managing bots, contacts, messages and flows from your server, authenticated with virtual user tokens. 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 [#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](https://chatfuel.com/docs/public-api/versioning). 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](https://chatfuel.com/docs/public-api/bots-and-account): the bot, its settings, the current account * [team and roles](https://chatfuel.com/docs/public-api/team-and-roles): virtual users, teammates and invites * [contacts](https://chatfuel.com/docs/public-api/contacts): contacts, attributes, assignees, notes, sales stages, CSV import and export * [messaging](https://chatfuel.com/docs/public-api/messaging): conversations and messages on every channel, WhatsApp templates * [flows](https://chatfuel.com/docs/public-api/flows): flows, blocks, keyword rules and test chats * [AI automations](https://chatfuel.com/docs/public-api/ai-automations): Fuely AI settings, automations and broadcasts * [bookings and catalog](https://chatfuel.com/docs/public-api/bookings-and-catalog): bookings, specialists, products and services * [channels](https://chatfuel.com/docs/public-api/channels): WhatsApp, Instagram, Facebook, TikTok and website widget settings * [files and tasks](https://chatfuel.com/docs/public-api/files-and-tasks): file upload and long-running tasks ## How access works: personal token and virtual users [#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](https://chatfuel.com/docs/public-api/authentication) compares the two tokens in detail, and [virtual users](https://chatfuel.com/docs/public-api/virtual-users) explains roles and limits. ## What a request looks like [#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: ```bash 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](https://chatfuel.com/docs/public-api/requests) covers pagination, subscriptions and file uploads, and [errors](https://chatfuel.com/docs/public-api/errors) lists the error codes. ## What you need to start [#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](https://chatfuel.com/docs/public-api/quickstart), which takes you from no token to your first API call. ## Limits at a glance [#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 [#common-issues] ### Requests from a web page fail with a CORS error [#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? [#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.