--- title: "Visão geral da Public API do Chatfuel" description: "A Public API do Chatfuel é uma API GraphQL para gerenciar bots, contatos, mensagens e fluxos a partir do seu servidor, com tokens de usuários virtuais." canonical_url: https://chatfuel.com/pt/docs/public-api/overview markdown_url: https://chatfuel.com/pt/docs/public-api/overview.md last_updated: 2026-10-06 lang: pt site: https://chatfuel.com/docs llms_txt: https://chatfuel.com/llms.txt --- # Visão geral da Public API do Chatfuel A Public API do Chatfuel é uma API GraphQL para gerenciar bots, contatos, mensagens e fluxos a partir do seu servidor, com tokens de usuários virtuais. 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 [#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](https://chatfuel.com/pt/docs/public-api/versioning). 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](https://chatfuel.com/pt/docs/public-api/bots-and-account): o bot, as configurações dele, a conta atual * [equipe e funções](https://chatfuel.com/pt/docs/public-api/team-and-roles): usuários virtuais, membros da equipe e convites * [contatos](https://chatfuel.com/pt/docs/public-api/contacts): contatos, atributos, responsáveis, notas, etapas de venda, importação e exportação de CSV * [mensagens](https://chatfuel.com/pt/docs/public-api/messaging): conversas e mensagens em todos os canais, templates do WhatsApp * [fluxos](https://chatfuel.com/pt/docs/public-api/flows): fluxos, blocos, regras de palavras-chave e chats de teste * [automações com IA](https://chatfuel.com/pt/docs/public-api/ai-automations): configurações do Fuely AI, automações e transmissões * [agendamentos e catálogo](https://chatfuel.com/pt/docs/public-api/bookings-and-catalog): agendamentos, especialistas, produtos e serviços * [canais](https://chatfuel.com/pt/docs/public-api/channels): configurações do WhatsApp, Instagram, Facebook, TikTok e do widget do site * [arquivos e tarefas](https://chatfuel.com/pt/docs/public-api/files-and-tasks): upload de arquivos e tarefas de longa duração ## Como funciona o acesso: token pessoal e usuários virtuais [#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](https://chatfuel.com/pt/docs/public-api/authentication) compara os dois tokens em detalhes, e [usuários virtuais](https://chatfuel.com/pt/docs/public-api/virtual-users) explica as funções e os limites. ## Como é uma requisição [#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`: ```bash 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](https://chatfuel.com/pt/docs/public-api/requests) cobre paginação, assinaturas e upload de arquivos, e [erros](https://chatfuel.com/pt/docs/public-api/errors) lista os códigos de erro. ## O que você precisa para começar [#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](https://chatfuel.com/pt/docs/public-api/quickstart), que leva você de nenhum token à sua primeira chamada de API. ## Limites em resumo [#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 [#problemas-comuns] ### Requisições feitas de uma página web falham com erro de CORS [#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? [#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.