--- title: "Referência da API: bots e conta" description: "Leia um bot e a conta atual com bot(id:) e currentUser. Renomear, excluir e criar bots e workspaces exige o token de API pessoal." canonical_url: https://chatfuel.com/pt/docs/public-api/bots-and-account markdown_url: https://chatfuel.com/pt/docs/public-api/bots-and-account.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Referência da API: bots e conta Leia um bot e a conta atual com bot(id:) e currentUser. Renomear, excluir e criar bots e workspaces exige o token de API pessoal. Toda chamada à Public API trabalha com um bot, e a consulta `bot(id:)` é o ponto de entrada para ler tudo o que há nele: contatos, conversas, fluxos, automações, agendamentos e configurações. A consulta `currentUser` retorna a conta associada ao token. Um usuário virtual pode ler o seu bot e a si mesmo; alterar configurações do bot, criar e excluir bots e gerenciar workspaces exige um [token de API pessoal](https://chatfuel.com/pt/docs/public-api/authentication). Cada operação abaixo indica a função de usuário virtual mais baixa que pode executá-la (**Agent** ou **Editor**), ou **Somente token pessoal** (nos comentários do código aparece como "Personal token only"). ## Como ler um bot [#como-ler-um-bot] `bot(id:)` retorna o bot se o dono do token for membro dele. Qualquer usuário virtual do bot pode lê-lo (**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 } } } ``` Os outros campos de `Bot` são abordados nas páginas de [contatos](https://chatfuel.com/pt/docs/public-api/contacts), [mensagens](https://chatfuel.com/pt/docs/public-api/messaging), [fluxos](https://chatfuel.com/pt/docs/public-api/flows), [automações de IA](https://chatfuel.com/pt/docs/public-api/ai-automations), [agendamentos e catálogo](https://chatfuel.com/pt/docs/public-api/bookings-and-catalog), [canais](https://chatfuel.com/pt/docs/public-api/channels) e [equipe e funções](https://chatfuel.com/pt/docs/public-api/team-and-roles). `Bot.usageStats(from: Time!, to: Time!, groupBy: UsageStatsGroupBy!)` retorna os gastos do bot divididos por `Day` ou `Month` (**Agent**). ## Como ler a conta atual [#como-ler-a-conta-atual] `currentUser` retorna a conta dona do 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 } } } } ``` Com um token de usuário virtual, `currentUser` é o próprio usuário virtual com `accountType: Virtual`, e `botsV2` retorna apenas o bot dele. Com um token de API pessoal, `botsV2` lista todos os bots a que você tem acesso. Para restringir a lista, filtre por título do bot ou por workspace, por exemplo `filter: { field: WorkspaceID, value: { type: Eq, val: "your-workspace-id" } }`, e ordene com `orderBy: { orderBy: LastOpenedAt, direction: … }`, em que `orderBy` é `LastOpenedAt`, `CreatedAt`, `Title` ou `Usage`. O seu e-mail e as suas contas sociais vinculadas só ficam disponíveis com o token de API pessoal. ## Configurações do bot [#configurações-do-bot] As configurações do bot só podem ser alteradas por um Admin do bot, então todas elas exigem um token de API pessoal: ```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! } ``` ## Como criar e excluir bots [#como-criar-e-excluir-bots] Criar e excluir bots é uma ação no nível da conta e sempre exige um token de API pessoal: ```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! } ``` Depois de criar um bot, crie nele um usuário virtual com `createVirtualUser`, como descrito em [usuários virtuais](https://chatfuel.com/pt/docs/public-api/virtual-users), e use esse token para tudo dentro do novo bot. ## Workspaces e faturamento [#workspaces-e-faturamento] Os workspaces agrupam bots sob uma única assinatura. Usuários virtuais nunca são membros de um workspace, então toda operação de workspace exige um token de API pessoal: ```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! } ``` Um `Workspace` expõe `id`, `title`, `bots`, `botsLimit`, `subscription` e `usageStats(from, to, groupBy, botIDs)`. Um usuário virtual pode ler `Bot.workspace { id title }` do próprio bot, mas não a assinatura nem o uso do workspace. ## Outras operações da conta [#outras-operações-da-conta] ```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! } ``` ## Problemas comuns [#problemas-comuns] ### "NotEnoughPermissions" ao renomear um bot ou alterar o fuso horário dele [#notenoughpermissions-ao-renomear-um-bot-ou-alterar-o-fuso-horário-dele] As configurações do bot exigem o token de API pessoal de um Admin do bot. Usuários virtuais, mesmo com a função Editor, não podem alterá-las. ### "BotInvalidTimezone" [#botinvalidtimezone] `botUpdateTimezone` aceita nomes de fuso horário IANA, como `America/Mexico_City`. Abreviações como `PST` e deslocamentos UTC são rejeitados. ### "OpenAIModelNotAvailable" [#openaimodelnotavailable] `botSetOpenAIModel` aceita apenas os modelos listados em `bot.openAIModelOptions` para esse bot.