Skip to main content

O que a API v3 faz e como começar

A API pública do AtendeBot é uma API REST para conectar sua conta a sistemas externos: n8n, Make, um sistema próprio ou de um parceiro. A autenticação é por token Bearer, e cada token carrega os escopos que definem o que ele pode ler e escrever.

A v3, documentada aqui, é a versão atual da API. A v2 (/public/v2/docs) continua no ar com o comportamento congelado; integrações novas devem nascer na v3, e quem vem da v2 encontra o de-para na seção Migrando da v2 da referência.

Objetivo

Gerar um token com os escopos certos e fazer a primeira chamada à API pública v3.

Pré-requisitos

  • Perfil Administrador.
  • Um token de API: veja tokens-api.

Tempo estimado

5 minutos.

Caminho de acesso

Ajustes → API e webhooks → Tokens (para gerar o token) e a referência viva da v3, em https://api.atende.bot/public/v3/docs.

Passo a passo

  1. Gere um token em Ajustes → API e webhooks → Tokens e marque os escopos da integração. Cada recurso tem um escopo de leitura e um de escrita (ex.: conversations:read/conversations:write, messages:write, cards:write, contacts:read). write não libera read. O envio de e-mail tem permissão própria, E-mails transacionais, e token com Acesso total não a inclui: edite o token e marque E-mails (veja receita-enviar-email-transacional).

  2. Faça a primeira chamada, trocando SEU_TOKEN pelo token gerado:

    curl https://api.atende.bot/public/v3/conversations?page_size=5 \
  -H "Authorization: Bearer SEU_TOKEN"

  3. A resposta traz o envelope padrão de listagem: { "data": [...], "meta": { "page": 1, "page_size": 5, "has_more": true, "total": null } }. total só vem quando você pede with_total=true; has_more vem sempre.

  4. Para o contrato completo de cada recurso, use a referência viva em https://api.atende.bot/public/v3/docs, gerada dos schemas das rotas, com try-it. Esta central cobre receitas prontas, não o dicionário de campos.

Resultado esperado

Token ATIVO com os escopos certos; a chamada de teste devolve 200 com o envelope { data, meta }.

Erros comuns

  • Sintoma: 401. Solução: confira o header Authorization: Bearer ... e se o token não está REVOGADO.
  • Sintoma: 403 de escopo insuficiente. Solução: adicione o escopo que falta ao token em Ajustes → API e webhooks → Tokens (em um token existente, use Editar escopos na linha do token e salve).
  • Sintoma: preciso abrir chamado de suporte sobre uma chamada que falhou. Solução: todo erro vem com error.details.request_id; envie esse valor junto do chamado.

Artigos relacionados

  • tokens-api
  • webhooks
  • receita-distribuir-atendimento
  • receita-enviar-email-transacional