Transport and auth

There is one endpoint per environment rather than one per account, and the botID inside the operation selects the project.

Appending ?op=<OperationName> to the HTTP URL is optional and useful: the server ignores it and the operation still travels in the POST body, but proxy and upstream logs become readable. The SDK's client adds it for every named operation.

How the token travels

A browser cannot set a header on a WebSocket handshake, which is why the socket carries the credential in a message instead. With the graphql-ws client that is connectionParams:

connectionParams: async () => {
  const value = options.getToken ? await options.getToken() : undefined;
  return value ? { authToken: `Bearer ${value}` } : {};
},

A raw WebSocket is not subject to a CORS preflight, so a subscription can technically connect from a foreign origin — but only by shipping a full-account credential to the browser. Both transports go through a proxy for that reason; see the token boundary.

What the token is

A Chatfuel token is a dashboard user token. The account owner generates it at https://panel.chatfuel.com/integration/auth/token, and rotation means generating a new one there. Assume nothing about its shape or its lifetime: it is an opaque secret that can be regenerated at any time, and it is a full-account credential, so it belongs on a server.

bot.apiToken is a different credential. It authenticates the separate REST APIs — broadcasting, contact import — and does not work for GraphQL. It is scoped to one bot, it outlives the session, and it reaches Chatfuel with nothing in front of it, so reading it once out of the schema is a permanent way around whatever your own backend does.

When a token stops working, every request comes back with an Unauthorized code. That is a rotation signal, not a transient failure: surface it and stop, rather than retrying.

An auth attempt can also come back as AuthResultRedirectToOldDashboard rather than AuthResultRegular. That is not a session and nothing downstream works with it — handle both branches of the union. Passing forceAuthFromCfProductsSwitcher: true to the auth mutations keeps eligible accounts on this product.

What the token may do

Permissions are per bot. A role is a type plus a list of (object, action) pairs:

Inbox gates live chat, People gates contacts, and ContactsAssignedToOthers / ContactsUnassigned are visibility restrictions — a restricted caller still receives a Contact, but it is an UnavailableContact stub with every field empty. The two actions are independent: Edit does not imply View, so a gate that means "may open this page" lists both pairs.

MyBotRole is the operation that answers all of it before you build UI that assumes edit rights:

query MyBotRole($botID: BotID!) {
  currentUser {
    id
    botRole(botID: $botID) {
      ...RoleInfo
    }
  }
}

How the WebSocket client behaves

One lazy connection per token: it opens on the first subscription and every subscription after that shares it.

graphql-ws already hard-fails on all six except 4403, so a client on that library needs to add only that one to its retry predicate. A clean idle close (1000) from the lazy connection is not a reconnect and must not trigger refetches.

Rate limiting

The API rate-limits per token, so batch reads and back off on 429. The SDK's client takes an optional token bucket — a requests-per-second rate and a concurrency cap, with a bulk preset of 5 rps at concurrency 2 — and surfaces every 429 as an HTTP error rather than a GraphQL one so the retry path can see it. Without that option there is no throttling at all, which is the right default for a UI a human is pacing.

What gets retried depends on whether a repeat is safe:

Query size guards also exist. Nothing in the shipped operations comes close to them.

Where several people share one token through a proxy, a per-user limit under Chatfuel's own ceiling is what stops one of them exhausting the budget for everyone.