---
title: "Bots and Account API Reference"
description: "Read a bot and the current account with bot(id:) and currentUser. Renaming, deleting and creating bots and workspaces needs the personal API token."
canonical_url: https://chatfuel.com/docs/public-api/bots-and-account
markdown_url: https://chatfuel.com/docs/public-api/bots-and-account.md
last_updated: 2026-10-06
lang: en
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# 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.

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](https://chatfuel.com/docs/public-api/authentication).

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 [#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**).

```graphql
type Query {
  bot(id: BotID!): Bot!
}
```

```graphql
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](https://chatfuel.com/docs/public-api/contacts), [messaging](https://chatfuel.com/docs/public-api/messaging), [flows](https://chatfuel.com/docs/public-api/flows), [AI automations](https://chatfuel.com/docs/public-api/ai-automations), [bookings and catalog](https://chatfuel.com/docs/public-api/bookings-and-catalog), [channels](https://chatfuel.com/docs/public-api/channels) and [team and roles](https://chatfuel.com/docs/public-api/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 [#how-to-read-the-current-account]

`currentUser` returns the account that owns the token.

```graphql
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-settings]

Bot-level settings are changed by bot Admins only, so all of them need a personal API token:

```graphql
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 [#how-to-create-and-delete-bots]

Creating and deleting bots is an account-level action and always needs a personal API token:

```graphql
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](https://chatfuel.com/docs/public-api/virtual-users), and use that token for everything inside the new bot.

## Workspaces and billing [#workspaces-and-billing]

Workspaces group bots under one subscription. Virtual users are never workspace members, so every workspace operation needs a personal API token:

```graphql
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 [#other-account-operations]

```graphql
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 [#common-issues]

### "NotEnoughPermissions" when renaming a bot or changing its timezone [#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" [#botinvalidtimezone]

`botUpdateTimezone` accepts IANA timezone names such as `America/Mexico_City`. Abbreviations like `PST` and UTC offsets are rejected.

### "OpenAIModelNotAvailable" [#openaimodelnotavailable]

`botSetOpenAIModel` accepts only models listed in `bot.openAIModelOptions` for that bot.