---
title: "Guia de início rápido da Public API do Chatfuel"
description: "Crie um token de API pessoal, encontre o ID do bot, crie um usuário virtual e faça sua primeira consulta e mutação na Public API em cerca de dez minutos."
canonical_url: https://chatfuel.com/pt/docs/public-api/quickstart
markdown_url: https://chatfuel.com/pt/docs/public-api/quickstart.md
last_updated: 2026-10-06
lang: pt
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Guia de início rápido da Public API do Chatfuel

Crie um token de API pessoal, encontre o ID do bot, crie um usuário virtual e faça sua primeira consulta e mutação na Public API em cerca de dez minutos.

O guia de início rápido leva você de nenhum token a uma chamada funcional à Public API do Chatfuel em cinco etapas: criar o seu token de API pessoal, encontrar o ID do bot, criar um usuário virtual, ler contatos com o token do usuário virtual e alterar um contato. Você precisa da função **Admin** no bot, de um terminal com `curl` e `jq` e de cerca de dez minutos.

## Etapa 1: Crie o seu token de API pessoal [#etapa-1-crie-o-seu-token-de-api-pessoal]

No painel do Chatfuel, o token de API pessoal se chama **CLI token**. Você o usa apenas para gerenciar usuários virtuais e outras configurações no nível da conta.

1. Entre no painel do Chatfuel em panel.chatfuel.com.
2. Abra o menu da conta (seu nome ou avatar) e selecione **CLI token**. A página também está disponível diretamente em `https://panel.chatfuel.com/integration/auth/token`.
3. Clique em **Create token** e depois em **Copy token**.
4. Salve o token de API pessoal em um gerenciador de senhas ou em um cofre de segredos. O Chatfuel mostra o token apenas uma vez.

Mantenha o token de API pessoal em uma variável de ambiente durante o resto do guia:

```bash
export CHATFUEL_PERSONAL_TOKEN="paste-your-cli-token-here"
```

Qualquer pessoa com o token de API pessoal pode agir como você em todos os bots aos quais você tem acesso. Nunca faça commit dele em um repositório nem o coloque em código do lado do cliente.

## Etapa 2: Encontre o ID do seu bot [#etapa-2-encontre-o-id-do-seu-bot]

Toda operação da Public API funciona dentro de um bot. Liste os bots que a sua conta pode acessar com o token de API pessoal:

```bash
QUERY='query MyBots {
  currentUser {
    botsV2(first: 50) {
      edges { node { id title } }
    }
  }
}'

jq -n --arg query "$QUERY" '{query: $query}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_PERSONAL_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

O ID do bot também aparece na barra de endereços do painel: é a parte depois de `/automation/` quando um bot está aberto. Salve-o:

```bash
export BOT_ID="your-bot-id"
```

## Etapa 3: Crie um usuário virtual [#etapa-3-crie-um-usuário-virtual]

Um usuário virtual é um membro de um bot que usa apenas a API. Ele recebe o próprio token, que você usa em todas as outras chamadas. Crie um com a mutação `createVirtualUser` e o token de API pessoal:

```bash
QUERY='mutation CreateVirtualUser($botID: BotID!) {
  createVirtualUser(
    botID: $botID
    name: "Quickstart integration"
    role: { roleType: Editor, botPermissions: [] }
  ) {
    member { id role { roleTypeV2 } user { id name accountType } }
    authToken
  }
}'

jq -n --arg query "$QUERY" --arg botID "$BOT_ID" \
  '{query: $query, variables: {botID: $botID}}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_PERSONAL_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

A resposta contém o novo membro e o token dele:

```json
{
  "data": {
    "createVirtualUser": {
      "member": {
        "id": "6f1c…",
        "role": { "roleTypeV2": "Editor" },
        "user": { "id": "6f1b…", "name": "Quickstart integration", "accountType": "Virtual" }
      },
      "authToken": "3c9e…"
    }
  }
}
```

`authToken` aparece somente nesta resposta. Salve-o junto com `member.id`, de que você vai precisar depois para regenerar o token ou remover o usuário virtual:

```bash
export CHATFUEL_VIRTUAL_USER_TOKEN="paste-authToken-here"
```

A função pode ser `Editor` ou `Agent`. [Usuários virtuais](https://chatfuel.com/pt/docs/public-api/virtual-users) explica o que cada função permite.

## Etapa 4: Leia contatos com o token do usuário virtual [#etapa-4-leia-contatos-com-o-token-do-usuário-virtual]

Troque para o token do usuário virtual e leia o título do bot e os dez primeiros contatos:

```bash
QUERY='query Contacts($botID: BotID!) {
  bot(id: $botID) {
    title
    contactsConnection(platforms: [whatsapp, instagram, facebook, tiktok, widget], first: 10) {
      edges { node { id name note updatedAt } }
      pageInfo { hasNextPage endCursor }
    }
  }
}'

jq -n --arg query "$QUERY" --arg botID "$BOT_ID" \
  '{query: $query, variables: {botID: $botID}}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

Para obter a próxima página, passe `pageInfo.endCursor` como o argumento `after`. [Como fazer requisições](https://chatfuel.com/pt/docs/public-api/requests) mostra o padrão completo de paginação.

## Etapa 5: Altere um contato [#etapa-5-altere-um-contato]

Pegue um `id` de contato da resposta anterior e defina uma nota nele com `contactSetNote`:

```bash
export CONTACT_ID="a-contact-id-from-step-4"

QUERY='mutation SetNote($contactID: ContactID!, $note: String) {
  contactSetNote(id: $contactID, note: $note) { id note }
}'

jq -n --arg query "$QUERY" --arg contactID "$CONTACT_ID" --arg note "Synced from CRM" \
  '{query: $query, variables: {contactID: $contactID, note: $note}}' |
curl -s https://panel.chatfuel.com/graphql \
  -H "Authorization: Bearer $CHATFUEL_VIRTUAL_USER_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-
```

A nota agora aparece no card do contato no painel, e o usuário virtual aparece entre os membros da equipe do bot com o rótulo **API**. A partir daqui, explore a [referência de contatos](https://chatfuel.com/pt/docs/public-api/contacts) e a [referência de mensagens](https://chatfuel.com/pt/docs/public-api/messaging), ou leia sobre [tokens e autenticação](https://chatfuel.com/pt/docs/public-api/authentication) antes de ir para produção.

## Problemas comuns [#problemas-comuns]

### "NotEnoughPermissions" ao criar um usuário virtual [#notenoughpermissions-ao-criar-um-usuário-virtual]

`createVirtualUser` só funciona com o token de API pessoal de um usuário que tem a função **Admin** no bot. Um token de usuário virtual é sempre rejeitado nessa mutação, mesmo que o usuário virtual exista no mesmo bot.

### "VirtualUserRoleNotAllowed" [#virtualuserrolenotallowed]

A função deve ser `Editor` ou `Agent`. Usuários virtuais não podem ser Admin nem ter uma função Custom.

### "Unauthorized" [#unauthorized]

O token está ausente, foi digitado errado ou foi revogado, ou falta o prefixo `Bearer ` no cabeçalho. Envie `Authorization: Bearer <token>` e confira se o token não foi regenerado nesse meio-tempo.