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.
Última atualização
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.
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
bot(id:) retorna o bot se o dono do token for membro dele. Qualquer usuário virtual do bot pode lê-lo (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 }
}
}Os outros campos de Bot são abordados nas páginas de contatos, mensagens, fluxos, automações de IA, agendamentos e catálogo, canais e equipe e funções.
Bot.usageStats(from: Time!, to: Time!, groupBy: UsageStatsGroupBy!) retorna os gastos do bot divididos por Day ou Month (Agent).
Como ler a conta atual
currentUser retorna a conta dona do 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 }
}
}
}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
As configurações do bot só podem ser alteradas por um Admin do bot, então todas elas exigem um token de API pessoal:
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
Criar e excluir bots é uma ação no nível da conta e sempre exige um token de API pessoal:
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, e use esse token para tudo dentro do novo bot.
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:
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
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
"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"
botUpdateTimezone aceita nomes de fuso horário IANA, como America/Mexico_City. Abreviações como PST e deslocamentos UTC são rejeitados.
"OpenAIModelNotAvailable"
botSetOpenAIModel aceita apenas os modelos listados em bot.openAIModelOptions para esse bot.
Versionamento e descontinuação da Public API
A Public API tem um único endpoint sem versão. Campos publicados nunca quebram: as mudanças são aditivas e remoções são antes marcadas como obsoletas.
Referência da API de equipe e funções
Liste membros e convites, e crie, renove, mude a função ou remova usuários virtuais. Alterar a equipe exige o token de API pessoal de um Admin.