# Chatfuel GraphQL — core operations every module needs (chatfuel-core skill):
# identity, bot discovery, permission check, file readback, channels and platform links.
# Validate against references/schema.graphql (node scripts/validate-operations.mjs).
# Transport & auth: references/transport-auth.md. Files & tasks: references/files-tasks.md.
# ============================================================
# Fragments
# ============================================================
fragment RoleInfo on Role {
roleTypeV2
botPermissions {
object
action
}
}
fragment BotInfo on Bot {
id
title
isReady
timezone
workspace {
id
title
}
}
# ============================================================
# Identity & bot discovery
# ============================================================
query CurrentUser {
currentUser {
id
name
email
dashboardLocale
countryCode
isWhiteLabel
profilePicture {
id
url
}
}
}
# The shared bot picker: how you discover botIDs once the token works.
query BotsList($first: Int, $after: BotsCursor, $filter: BotsFilter, $orderBy: BotsOrderByInput) {
currentUser {
id
botsV2(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
edges {
node {
...BotInfo
}
}
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
}
}
}
# The Chatfuel workspace is the BILLING container: an agency pays for a
# workspace, and every bot inside it draws on that payment. `workspaces` lives
# on currentUser (there is no root `workspaces` field).
query WorkspacesList {
currentUser {
id
workspaces {
id
title
botsLimit
bots {
id
title
}
}
}
}
# Creates a bot INSIDE a workspace. `createBot` without one makes a throwaway
# workspace per bot (and leaves it behind when the bot is deleted), so anything
# that must bill to a paid workspace goes through this mutation.
# Errors arrive nested: errors[].extensions.errors[].extensions.code —
# TooManyBotsInWorkspace when the plan's bot limit is reached,
# NotEnoughPermissions when the id is unknown or belongs to somebody else.
mutation WorkspaceCreateBot($workspaceID: WorkspaceID!, $initialTitle: String!) {
workspaceCreateBot(workspaceID: $workspaceID, initialTitle: $initialTitle) {
id
title
}
}
# Own role + permissions in a bot. PermissionObject values gate each domain
# (Inbox = live chat, People = contacts, etc.) — see references/transport-auth.md.
query MyBotRole($botID: BotID!) {
currentUser {
id
botRole(botID: $botID) {
...RoleInfo
}
}
}
# ============================================================
# Files (uploads are REST — see references/files-tasks.md)
# ============================================================
query FileGet($fileID: FileID!) {
file(id: $fileID) {
id
url
type
status
size
}
}
mutation FileStartDownload($fileID: FileID!) {
fileStartDownload(id: $fileID) {
id
url
type
status
size
}
}
# ============================================================
# Per-user storage
# ============================================================
# `setUserStorageItem` is the ONLY persistence this API offers a client, and it
# is scoped to the SIGNED-IN USER, not to the team or the bot. Any UI built on
# it must say "your views", never "shared views".
#
# It lives in core rather than in a module because it is a generic mechanism —
# an arbitrary id, an arbitrary string — that any module can use: a module may
# import `~api/generated/core` and nothing else, so one pair here serves all ten.
#
# `value` is nullable: an id that was never written reads back as an item with
# `value: null` rather than erroring, so a first-run read needs no special case.
# The stored string is UNTRUSTED — it is whatever some past version of the app
# wrote, and it must be parsed defensively rather than cast.
query UserStorageGet($id: ID!) {
currentUser {
id
userStorageItem(id: $id) {
id
value
}
}
}
mutation UserStorageSet($id: ID!, $value: String!) {
setUserStorageItem(id: $id, value: $value) {
id
value
}
}
# ============================================================
# Whole-bot preview session (seeding only)
# ============================================================
# `previewResponsesStartForBot` mints a preview conversation on a synthetic
# contact and runs the bot's real pipeline against it. No module ships a UI for
# it — testing happens where the work is, pinned to one flow (flow-builder) or
# one automation (automations), and each of those owns its own start mutation.
#
# It lives in core because three SEED RECIPES need it and nothing else does:
# livechat, contacts and deals all bootstrap a demo conversation with it, and a
# recipe may not reach into another module's generated documents any more than
# app code may. One pair here serves all three.
#
# `ScopeNotConnectedToBot` is the expected refusal when the platform is not
# wired to the bot — recipes walk the platform list and try the next one.
fragment PreviewBotSessionParts on PreviewResponsesBotSession {
id
conversationID
startedAt
platform
}
mutation PreviewStartForBot($botID: BotID!, $platform: Platform!) {
previewResponsesStartForBot(botID: $botID, platform: $platform) {
...PreviewBotSessionParts
}
}
# Seeds one contact-side message into that conversation. The result is the echo
# of what you just sent; recipes do not read it, so it stays two fields wide.
mutation PreviewWidgetTextSend(
$botID: BotID!
$conversationID: ConversationID!
$message: WidgetTextMessageSendInput!
) {
previewResponsesWidgetTextSend(botID: $botID, conversationID: $conversationID, message: $message) {
id
clientId
}
}
# ============================================================
# Channels & platform links
# ============================================================
# A platform link is a one-shot URL on Chatfuel's own page, valid for 24 hours
# from creation, that lets somebody who is NOT a member of the bot either
# connect a new WhatsApp phone / Instagram account / TikTok account to it
# (connection link) or re-grant the permissions on the asset already connected
# (access-refresh link). The page, the OAuth round trip and the provider
# redirect URIs are all Chatfuel's, so an app never hosts the consume side: it
# mints the link, hands over `url`, and reads the active map back. Full rules:
# references/platform-links.md.
#
# One active link per (bot, platform, kind): a second create silently replaces
# the first, whose URL then stops working. `PlatformOperationLinkPlatform` has
# no facebook member — a Facebook page is connected through the signed-in
# OAuth route instead.
#
# Error codes: PlatformNotSupportedForOperationLink,
# PlatformOperationLinkInvalidRedirectURL (redirect URLs must be https:// with
# a host), NoConnectedContactScopeForPlatform (access-refresh only: nothing of
# that platform is connected yet), PlatformOperationLinkNotFound (revoking a
# link that is no longer active), NotEnoughPermissions (Configure / Edit).
# Which channels the bot has. `contactScopes` needs access to the bot only; the
# link maps further down need Configure / Edit and are non-null, which is why
# they are a separate document — one that asked for both would answer nothing
# at all to a role that may read but not manage.
fragment BotChannelsParts on Bot {
id
contactScopes {
__typename
id
... on WhatsAppPhoneContactScope {
phone {
id
displayPhoneNumber
verifiedName
}
}
... on InstagramAccountContactScope {
instagramAccount {
id
username
name
}
}
... on TikTokAccountContactScope {
tiktokAccount {
id
username
name
}
}
... on FacebookContactScope {
facebookPage {
id
name
}
}
... on WebWidgetContactScope {
webWidget {
id
name
}
}
}
}
query BotChannels($botID: BotID!) {
bot(id: $botID) {
...BotChannelsParts
}
}
fragment PlatformConnectionLinkParts on PlatformConnectionLink {
linkID
url
platform
createdAt
expiresAt
onSuccessRedirectURL
onFailureRedirectURL
creator {
id
name
}
}
# `connectedContactScope` is an interface; the four concrete types the enum
# allows are selected, and `__typename` tells them apart. TikTok's `username`
# is nullable, Instagram's is not. A Facebook refresh link is bound to ONE page.
fragment PlatformAccessRefreshLinkParts on PlatformAccessRefreshLink {
linkID
url
platform
createdAt
expiresAt
onSuccessRedirectURL
onFailureRedirectURL
creator {
id
name
}
connectedContactScope {
__typename
... on PublicWhatsAppPhoneContactScope {
phone {
displayPhoneNumber
verifiedName
}
}
... on PublicInstagramAccountContactScope {
instagramAccount {
username
name
}
}
... on PublicTikTokAccountContactScope {
tiktokAccount {
username
name
}
}
... on PublicFacebookContactScope {
facebookPage {
id
name
}
}
}
}
# The whole active map, one slot per platform, null where nothing is active.
# Spread on the `Bot!` the revoke and disconnect mutations return, so none of
# them needs a refetch.
fragment ActivePlatformLinks on Bot {
id
activePlatformConnectionLinks {
whatsapp {
...PlatformConnectionLinkParts
}
instagram {
...PlatformConnectionLinkParts
}
tiktok {
...PlatformConnectionLinkParts
}
facebook {
...PlatformConnectionLinkParts
}
}
activePlatformAccessRefreshLinks {
whatsapp {
...PlatformAccessRefreshLinkParts
}
instagram {
...PlatformAccessRefreshLinkParts
}
tiktok {
...PlatformAccessRefreshLinkParts
}
facebook {
...PlatformAccessRefreshLinkParts
}
}
}
query BotPlatformLinks($botID: BotID!) {
bot(id: $botID) {
...ActivePlatformLinks
}
}
# Configure / Edit. The web widget is refused (CannotDisconnectWidgetScope); a
# scope that is already gone answers ContactScopeDoesNotExist. Disconnecting
# revokes the access-refresh link bound to that scope, so the payload carries
# both the scopes and the link maps.
mutation BotDisconnectContactScope($botID: BotID!, $contactScopeID: ContactScopeID!) {
botDisconnectContactScope(botID: $botID, contactScopeID: $contactScopeID) {
...BotChannelsParts
...ActivePlatformLinks
}
}
# Answers the new link with `url` — hand that string to the person who will
# open it. `linkID` is the same secret in another form: treat both as
# credentials. Replaces any active connection link for that platform.
mutation BotPlatformConnectionLinkCreate(
$botID: BotID!
$platform: PlatformOperationLinkPlatform!
$onSuccessRedirectURL: String
$onFailureRedirectURL: String
) {
botPlatformConnectionLinkCreate(
botID: $botID
platform: $platform
onSuccessRedirectURL: $onSuccessRedirectURL
onFailureRedirectURL: $onFailureRedirectURL
) {
...PlatformConnectionLinkParts
}
}
mutation BotPlatformConnectionLinkRevoke($botID: BotID!, $linkID: PlatformOperationLinkID!) {
botPlatformConnectionLinkRevoke(botID: $botID, linkID: $linkID) {
...ActivePlatformLinks
}
}
# Needs a connected scope of that platform, or NoConnectedContactScopeForPlatform.
# The link is bound to that scope: disconnecting it revokes the link.
mutation BotPlatformAccessRefreshLinkCreate(
$botID: BotID!
$platform: PlatformOperationLinkPlatform!
$onSuccessRedirectURL: String
$onFailureRedirectURL: String
) {
botPlatformAccessRefreshLinkCreate(
botID: $botID
platform: $platform
onSuccessRedirectURL: $onSuccessRedirectURL
onFailureRedirectURL: $onFailureRedirectURL
) {
...PlatformAccessRefreshLinkParts
}
}
mutation BotPlatformAccessRefreshLinkRevoke($botID: BotID!, $linkID: PlatformOperationLinkID!) {
botPlatformAccessRefreshLinkRevoke(botID: $botID, linkID: $linkID) {
...ActivePlatformLinks
}
}