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

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

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:

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

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:

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:

export BOT_ID="your-bot-id"

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:

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:

{
  "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:

export CHATFUEL_VIRTUAL_USER_TOKEN="paste-authToken-here"

A função pode ser Editor ou Agent. Usuários virtuais explica o que cada função permite.

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:

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 mostra o padrão completo de paginação.

Etapa 5: Altere um contato

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

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 e a referência de mensagens, ou leia sobre tokens e autenticação antes de ir para produção.

Problemas comuns

"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"

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

"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.