Autenticação e tokens da Public API

A Public API do Chatfuel autentica cada requisição com um token no cabeçalho Authorization: Bearer <token>. Existem dois tipos de token: o seu token de API pessoal, chamado de CLI token no painel, e os tokens de usuários virtuais, que pertencem a membros de um único bot que usam apenas a API. Use tokens de usuários virtuais no trabalho de integração do dia a dia e reserve o token de API pessoal para as poucas operações que exigem uma pessoa real.

Como enviar um token

Envie o token no cabeçalho Authorization de toda requisição HTTP:

POST /graphql HTTP/1.1
Host: panel.chatfuel.com
Authorization: Bearer 3c9e5f…
Content-Type: application/json

Para assinaturas GraphQL via WebSocket, coloque o mesmo valor no payload de inicialização da conexão como authToken:

{ "authToken": "Bearer 3c9e5f…" }

Os tokens são strings opacas de 64 caracteres hexadecimais. Não faça parse deles nem dependa do formato. Uma requisição sem um token válido ainda pode chegar à API, mas toda operação que precisa de um usuário falha com Unauthorized.

Token de API pessoal vs. token de usuário virtual

Os dois tokens chamam o mesmo endpoint e as mesmas operações. Uma operação que funciona dentro de um bot dá o mesmo resultado com qualquer um dos tokens, desde que a função permita. A diferença é o escopo: um token de API pessoal vazado expõe toda a sua conta, enquanto um token de usuário virtual vazado expõe um único bot com uma função limitada.

Como criar, regenerar e revogar o token de API pessoal

O token de API pessoal é gerenciado somente no painel do Chatfuel, nunca pela API:

1. Abra o menu da conta (seu nome ou avatar) e selecione CLI token, ou acesse https://panel.chatfuel.com/integration/auth/token.
2. Clique em Create token e copie-o. O Chatfuel mostra o token de API pessoal apenas uma vez.
3. Para substituir um token perdido ou exposto, clique em Regenerate token. O token antigo para de funcionar na hora, e o novo é exibido uma única vez.
4. Para desativar o token, clique em Revoke token. Tudo o que o usa perde o acesso imediatamente.

Cada conta tem exatamente um token de API pessoal por vez. Usuários virtuais não podem criar um token de API pessoal para si mesmos.

Como obter e rotacionar o token de um usuário virtual

O token de um usuário virtual é retornado uma única vez por createVirtualUser. Para rotacioná-lo, chame regenerateVirtualUserToken com o ID de membro do usuário virtual: o token antigo para de funcionar e a resposta contém o novo. Para revogar o acesso por completo, remova o usuário virtual com removeMemberFromBot ou com Delete API user nos membros da equipe do bot. As três operações precisam do token de API pessoal de um Admin do bot. Usuários virtuais mostra cada chamada.

Operações que precisam do token de API pessoal

Um usuário virtual só funciona dentro do seu bot e só com a função Editor ou Agent. Operações que alteram a conta, a equipe, as conexões de canais ou os workspaces rejeitam tokens de usuários virtuais com NotEnoughPermissions e precisam de um token de API pessoal. As páginas de referência as marcam como Somente token pessoal (Personal token only). São elas:

• Equipe: createVirtualUser, regenerateVirtualUserToken, removeMemberFromBot, changeBotMemberRoleV2, createBotInviteV2, botInviteDelete, leaveBot
• Bot: renameBot, deleteBot, createWorkspaceAndBot, botUpdateRolesConfig, botResetAPIToken, botSetOpenAIModel, botUnsetOpenAIModel, updateUserOpenedBotDate
• Configurações do bot que exigem a função Admin: botUpdateTimezone, botUpdateCountryCode, botUpdateIndustry, botSetLivechatAutoClosingConfig
• Conexões de canais: botConnectFacebookPage, botConnectInstagramAccount, botConnectTikTokAccount, botDisconnectContactScope, as mutações botPlatformConnectionLink* e botPlatformAccessRefreshLink* e os campos Bot.activePlatform*Links, fbPagesSyncForBusiness, fbPageSyncLatestPosts, whatsAppEntitiesStartRefetch, whatsAppPhoneSyncBizAppData, whatsAppPhoneSetProfileImageFile
• Workspaces e cobrança: todas as mutações workspace*, currentUser.workspace e currentUser.workspaces, Workspace.subscription, Workspace.usageStats, a assinatura billingSubscriptionUpdated
• A sua própria conta: setUserDashboardLocale, availableGoogleCalendars

Como manter os tokens seguros

• Mantenha os tokens no seu servidor, em um gerenciador de segredos ou em variáveis de ambiente criptografadas. Nunca os envie para um navegador, um app móvel ou um repositório público.
• Crie um usuário virtual separado para cada integração ou para cada um dos seus clientes, para que um vazamento afete um único bot e uma única integração.
• Registre do seu lado qual usuário virtual pertence a qual dos seus usuários. O Chatfuel não sabe como você associa usuários virtuais aos seus clientes.
• Rotacione o token de um usuário virtual com regenerateVirtualUserToken quando alguém que tinha acesso sair, e regenere o token de API pessoal no painel se ele puder ter sido exposto.
• Não coloque tokens em URLs nem em logs.

Problemas comuns

"Unauthorized"

O token está ausente, foi digitado errado, regenerado ou revogado, ou o usuário virtual foi removido. Confira se o cabeçalho é exatamente Authorization: Bearer <token>.

"NotEnoughPermissions"

O token é válido, mas o dono dele não pode executar esta operação: um usuário virtual chamou uma operação da lista de token pessoal acima, ou a função do usuário virtual não permite. Um Agent, por exemplo, não pode editar fluxos. Troque para o token de API pessoal ou altere a função do usuário virtual.

"A token already exists for your account. Regenerate it to get a new one."

Cada conta tem um único token de API pessoal. O antigo não pode ser exibido de novo; clique em Regenerate token para obter um novo.