Visão geral da Public API do Chatfuel

A Public API do Chatfuel permite que o seu próprio software trabalhe com os bots do Chatfuel: ler e atualizar contatos, enviar mensagens pelo WhatsApp, Instagram, Facebook, TikTok e chat do site, gerenciar agendamentos e o catálogo, e criar fluxos e automações com IA. É uma API GraphQL em https://panel.chatfuel.com/graphql, feita para desenvolvedores que conectam o Chatfuel a um CRM, a uma ferramenta interna ou ao próprio produto.

O que a Public API cobre

A Public API é uma parte estável e documentada da mesma API GraphQL que o painel do Chatfuel usa. Só fazem parte dela os campos publicados explicitamente, então mudanças internas no painel nunca quebram a sua integração. Os campos publicados só mudam com a adição de novos campos ou argumentos; tudo o que vai ser removido é primeiro marcado como obsoleto e continua funcionando até uma data informada, como descrito em versionamento e descontinuação.

A Public API é organizada em torno de um bot. Tudo o que você pode ler ou alterar pertence a um bot e é acessado pela consulta bot(id:) ou por uma mutação que recebe um botID:

• bots e dados da conta: o bot, as configurações dele, a conta atual
• equipe e funções: usuários virtuais, membros da equipe e convites
• contatos: contatos, atributos, responsáveis, notas, etapas de venda, importação e exportação de CSV
• mensagens: conversas e mensagens em todos os canais, templates do WhatsApp
• fluxos: fluxos, blocos, regras de palavras-chave e chats de teste
• automações com IA: configurações do Fuely AI, automações e transmissões
• agendamentos e catálogo: agendamentos, especialistas, produtos e serviços
• canais: configurações do WhatsApp, Instagram, Facebook, TikTok e do widget do site
• arquivos e tarefas: upload de arquivos e tarefas de longa duração

Como funciona o acesso: token pessoal e usuários virtuais

A Public API aceita dois tipos de token, e eles não são equivalentes.

O token de API pessoal pertence a você, um usuário real do Chatfuel. No painel, ele se chama CLI token. Ele age com as suas próprias permissões em todos os bots dos quais você é membro. Use-o para um pequeno conjunto de operações no nível da conta: criar e remover usuários virtuais, gerenciar membros da equipe, renomear ou excluir bots, conectar canais e trabalhar com workspaces.

Um usuário virtual é uma conta exclusiva da API que você cria dentro de um bot com a função Editor ou Agent. Ele tem o próprio token, não pode entrar no painel e não vê nada fora do seu bot. Use tokens de usuários virtuais para todo o trabalho do dia a dia: contatos, mensagens, fluxos, automações, agendamentos. Todos os exemplos desta documentação usam um token de usuário virtual, a menos que indiquem Somente token pessoal (Personal token only).

Crie um usuário virtual por integração, ou um por cliente do seu produto. Se um token vazar, você remove um único usuário virtual em vez de perder o acesso a toda a sua conta. Autenticação compara os dois tokens em detalhes, e usuários virtuais explica as funções e os limites.

Como é uma requisição

Toda chamada é um POST HTTP com corpo JSON para https://panel.chatfuel.com/graphql. O token vai no cabeçalho Authorization com o esquema Bearer:

curl https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query Bot($id: BotID!) { bot(id: $id) { id title timezone } }","variables":{"id":"'"$BOT_ID"'"}}'

A resposta é um JSON padrão do GraphQL com data e, quando algo falha, errors. Como fazer requisições cobre paginação, assinaturas e upload de arquivos, e erros lista os códigos de erro.

O que você precisa para começar

Para começar a usar a Public API, você precisa de:

• Uma conta do Chatfuel com a função Admin no bot, porque só quem tem a função Admin no bot pode criar usuários virtuais.
• Um servidor ou job de backend para fazer as chamadas. A Public API é para uso servidor a servidor: navegadores em outros domínios são bloqueados pelo CORS, e os tokens nunca devem ser enviados para um navegador ou app móvel.
• Cerca de dez minutos para o guia de início rápido, que leva você de nenhum token à sua primeira chamada de API.

Limites em resumo

• Limite de taxa: 25 operações por segundo por conta. Cada usuário virtual tem o próprio limite.
• Usuários virtuais: até 20 por bot.
• Tamanho da página: até 500 itens por página para contatos, conversas e regras de palavras-chave.
• Tokens: exibidos uma única vez na criação e válidos por 10 anos, a menos que sejam revogados.

Problemas comuns

Requisições feitas de uma página web falham com erro de CORS

A Public API aceita requisições de navegador somente a partir do painel do Chatfuel. Chame-a do seu servidor e mantenha o token lá; a sua página web se comunica com o seu servidor.

Posso usar a chave de API de Settings → API?

A chave API nas configurações de um bot é uma chave diferente e mais antiga, usada nos endpoints de transmissões e importação de contatos. A Public API aceita apenas o token de API pessoal (CLI token) e tokens de usuários virtuais.