Bots and Account API Reference
Read a bot and the current account with bot(id:) and currentUser. Renaming, deleting and creating bots and workspaces needs the personal API token.
Last updated on
Every Public API call works with a bot, and the bot(id:) query is the entry point for reading everything inside it: contacts, conversations, flows, automations, bookings and settings. The currentUser query returns the account behind the token. A virtual user can read its bot and itself; changing bot-level settings, creating and deleting bots and managing workspaces need a personal API token.
Each operation below is marked with the lowest virtual user role that can run it (Agent or Editor), or Personal token only.
How to read a bot
bot(id:) returns the bot if the token's owner is a member of it. Any virtual user of the bot can read it (Agent).
type Query {
bot(id: BotID!): Bot!
}query BotInfo($botID: BotID!) {
bot(id: $botID) {
id
title
createdAt
timezone # IANA name, for example "America/Sao_Paulo"
countryCode # two-letter code, for example "BR"
isReady
openAIConfig { model }
openAIModelOptions { model isDefault }
}
}The other Bot fields are covered on the pages for contacts, messaging, flows, AI automations, bookings and catalog, channels and team and roles.
Bot.usageStats(from: Time!, to: Time!, groupBy: UsageStatsGroupBy!) returns the bot's spending broken down by Day or Month (Agent).
How to read the current account
currentUser returns the account that owns the token.
query Me {
currentUser {
id
name
accountType # Regular or Virtual
hasPublicAPIToken
botRole(botID: "your-bot-id") { roleTypeV2 }
botsV2(first: 50) {
edges { node { id title } }
pageInfo { hasNextPage endCursor }
}
}
}Under a virtual user token, currentUser is the virtual user itself with accountType: Virtual, and botsV2 returns only its own bot. Under a personal API token, botsV2 lists every bot you can access. To narrow the list, filter by bot title or workspace, for example filter: { field: WorkspaceID, value: { type: Eq, val: "your-workspace-id" } }, and sort with orderBy: { orderBy: LastOpenedAt, direction: … }, where orderBy is LastOpenedAt, CreatedAt, Title or Usage. Your email and linked social accounts are available only under the personal API token.
Bot settings
Bot-level settings are changed by bot Admins only, so all of them need a personal API token:
type Mutation {
# Personal token only (Admin). IANA timezone, for example "Europe/Madrid".
botUpdateTimezone(botID: BotID!, timezone: BotTimezone!): Bot!
# Personal token only (Admin). Two-letter country code.
botUpdateCountryCode(botID: BotID!, countryCode: CountryCode!): Bot!
# Personal token only (Admin).
botUpdateIndustry(botID: BotID!, industry: BotIndustryInput!): Bot!
# Personal token only.
renameBot(botID: BotID!, newTitle: String!): Bot!
# Personal token only. What Editors and Agents may do in this bot.
botUpdateRolesConfig(botID: BotID!, rolesConfig: RolesConfigInput!): Bot!
# Personal token only. Only models from Bot.openAIModelOptions are accepted.
botSetOpenAIModel(botID: BotID!, openAIModel: OpenAIModel!): Bot!
# Personal token only. Returns the bot to the default model.
botUnsetOpenAIModel(botID: BotID!): Bot!
# Personal token only. Resets the legacy bot API key from Settings → API.
botResetAPIToken(botID: BotID!): Bot!
# Personal token only. Marks the bot as recently opened for sorting by LastOpenedAt.
updateUserOpenedBotDate(botID: BotID!): CurrentUserAccount!
}How to create and delete bots
Creating and deleting bots is an account-level action and always needs a personal API token:
type Mutation {
# Personal token only. Creates a new workspace with one bot in it.
createWorkspaceAndBot(initialTitle: String!, timezone: BotTimezone): Bot!
# Personal token only. Creates a bot in an existing workspace.
workspaceCreateBot(workspaceID: WorkspaceID!, initialTitle: String!, timezone: BotTimezone): Bot!
# Personal token only. Deletes the bot and all of its virtual users.
deleteBot(botID: BotID!): CurrentUserAccount!
}After creating a bot, create a virtual user in it with createVirtualUser, as described in virtual users, and use that token for everything inside the new bot.
Workspaces and billing
Workspaces group bots under one subscription. Virtual users are never workspace members, so every workspace operation needs a personal API token:
type CurrentUserAccount {
# Personal token only.
workspaces: [Workspace!]!
workspace(id: WorkspaceID!): Workspace!
workspaceRoles: [WorkspaceRole!]!
}
type Mutation {
# Personal token only. Creates an empty workspace with a default title.
workspaceCreate: Workspace!
workspaceRename(workspaceID: WorkspaceID!, newTitle: String!): Workspace!
workspaceTransferBot(botID: BotID!, targetWorkspaceID: WorkspaceID!): Workspace!
# Only an empty workspace without an active paid subscription can be deleted.
workspaceDelete(workspaceID: WorkspaceID!): Boolean!
}
type Subscription {
# Personal token only. Fires when the workspace's billing subscription changes.
billingSubscriptionUpdated(workspaceID: WorkspaceID!): BillingSubscription!
}A Workspace exposes id, title, bots, botsLimit, subscription and usageStats(from, to, groupBy, botIDs). A virtual user can read Bot.workspace { id title } of its own bot but not the subscription or usage of the workspace.
Other account operations
type Query {
# Shows an invite before it is accepted. Virtual users can't accept invites.
inviteInfo(inviteToken: BotInviteToken!): Invite!
# Returns a Chatfuel dashboard text by its key, for example in DashboardLocale En, Es or Pt.
translation(key: String!, locale: DashboardLocale!): String!
}
type Mutation {
# Personal token only. Language of the Chatfuel dashboard for your account.
setUserDashboardLocale(locale: DashboardLocale!): CurrentUserAccount!
}Common issues
"NotEnoughPermissions" when renaming a bot or changing its timezone
Bot-level settings need the personal API token of a bot Admin. Virtual users, even with the Editor role, can't change them.
"BotInvalidTimezone"
botUpdateTimezone accepts IANA timezone names such as America/Mexico_City. Abbreviations like PST and UTC offsets are rejected.
"OpenAIModelNotAvailable"
botSetOpenAIModel accepts only models listed in bot.openAIModelOptions for that bot.