API e integrações

Conecte o AtendeBot ao n8n, Make ou ao seu sistema pela API pública v3.

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

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 Enviar um e-mail transacional pela API).

  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

Artigos relacionados

Distribuir um atendimento para um vendedor via n8n

Uma equipe de vendas recebe atendimentos novos e quer distribuí-los entre os vendedores automaticamente (por sorteio, por rodízio ou por uma regra, ex.: cliente de São Paulo vai para o vendedor X). Esta receita mostra como fazer isso com um fluxo no n8n chamando a API v3.

Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por O que a API v3 faz e como começar.

Objetivo

Definir a equipe e o responsável de um atendimento numa única chamada, a partir de um fluxo externo.

Pré-requisitos

Tempo estimado

10 minutos.

Caminho de acesso

Chamada direta à API: não há tela equivalente no AtendeBot para redistribuição vinda de fora.

Passo a passo

  1. No n8n, capture o id da conversa a partir do evento que dispara o fluxo: numa assinatura criada pela v3, o webhook message.received traz data.conversation.id (e a conversa já carregada em data.conversation, com assignee e team atuais).

  2. Escolha o vendedor (sorteio, rodízio ou regra num nó Function/Code) e monte team_id e assignee_id.

  3. Adicione um nó HTTP Request com PATCH para /public/v3/conversations/{id}, enviando team e assignee no mesmo corpo:

    {
  "parameters": {
    "method": "PATCH",
    "url": "https://api.atende.bot/public/v3/conversations/{{ $json.conversation_id }}",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpBearerAuth",
    "sendBody": true,
    "specifyBody": "json",
    "jsonBody": "={{ JSON.stringify({ team: $json.team_id, assignee: $json.assignee_id }) }}",
    "options": {}
  },
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 4.2,
  "name": "Distribuir atendimento",
  "credentials": {
    "httpBearerAuth": { "id": "1", "name": "AtendeBot API" }
  }
}

    Crie a credencial HTTP Bearer Auth do n8n com o token de API antes de importar o nó.

  4. O mesmo em cURL, para testar antes de montar o fluxo:

    curl -X PATCH https://api.atende.bot/public/v3/conversations/CONVERSATION_ID \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "team": "TEAM_ID", "assignee": "ASSIGNEE_ID" }'

Na v2, trocar de equipe (PUT /transfer) zerava o responsável, e por isso a integração precisava de dois nós. Na v3 os dois campos são aplicados juntos num único PATCH, e team sozinho não mexe no responsável. Migrando da v2: se seu fluxo fazia /transfer e depois /assignee, mande team e assignee no mesmo corpo, como acima; use "assignee": null só quando a intenção é devolver a conversa para a fila, pois zerar numa chamada e atribuir em outra grava duas transferências na trilha e dispara dois conversation.updated.

Resultado esperado

200 com a conversa atualizada; team e assignee voltam como objetos { id, name }.

Erros comuns

Artigos relacionados

Abrir um card no CRM quando chega uma mensagem

Quando um contato manda a primeira mensagem, você quer que uma negociação já apareça no funil de vendas, sem alguém abrir o card na mão. Esta receita liga o webhook message.received a um fluxo no n8n que cria o card via API v3.

Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por O que a API v3 faz e como começar.

Objetivo

Criar um card no CRM automaticamente a partir de uma mensagem recebida, sem duplicar card para quem já tem um aberto.

Pré-requisitos

Tempo estimado

15 minutos.

Caminho de acesso

Chamada direta à API, disparada pelo seu webhook: não há tela equivalente no AtendeBot.

Passo a passo

  1. Crie a assinatura do webhook no formato 3 (o que os passos abaixo esperam). Pela tela de Ajustes (API e webhooks → Webhooks) ela já nasce nesse formato: no diálogo, "Formato do payload" fica em v3, e o botão { } ao lado de cada evento abre o envelope de exemplo. Ou pela API:

    curl -X POST https://api.atende.bot/public/v3/webhooks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Card ao receber mensagem",
    "url": "https://SEU-N8N/webhook/xxxx",
    "events": [{ "name": "message.received" }],
    "secret": "UM_SEGREDO_SEU"
  }'

    No formato 3, o data traz conversation.id e contact.id.

    Se você só quer disparar este fluxo para mensagens de um canal específico (ex.: um número dedicado a vendas), acrescente filters ao item do evento (o escopo só existe no formato 3):

    "events": [{ "name": "message.received", "filters": { "channels": ["CHANNEL_ID"] } }]

  2. Se você ainda não tem os ids do funil e da etapa, liste-os uma vez:

    curl https://api.atende.bot/public/v3/pipelines \
  -H "Authorization: Bearer SEU_TOKEN"

  3. Antes de criar, confira se o contato já tem card aberto naquele funil, o que evita duplicar a negociação a cada nova mensagem:

    curl "https://api.atende.bot/public/v3/cards?contact=CONTACT_ID&pipeline=PIPELINE_ID" \
  -H "Authorization: Bearer SEU_TOKEN"

    Se data vier vazio, siga para o próximo passo; se já existir card, pule a criação.

  4. Crie o card, usando data.contact.id do webhook:

    curl -X POST https://api.atende.bot/public/v3/cards \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Novo contato via WhatsApp",
    "pipeline": "PIPELINE_ID",
    "stage": "STAGE_ID",
    "contact": "CONTACT_ID",
    "conversation": "CONVERSATION_ID"
  }'

    title é o único campo obrigatório; pipeline e/ou stage também precisam vir (ao menos um dos dois).

Esta chamada não é idempotente: retentar o mesmo POST por timeout de rede cria um segundo card. É por isso que o passo 3 importa: é a sua proteção contra duplicata, não um cache da API.

Resultado esperado

201 com o card criado, vinculado ao contato e à conversa; aparece no quadro Kanban na etapa escolhida.

Erros comuns

Artigos relacionados

Enviar um modelo (template) fora da janela de 24 h

No WhatsApp Oficial, você só pode mandar mensagem livre para um contato dentro de 24 horas da última mensagem dele. Passado esse prazo, a única forma de reabrir a conversa é enviar um modelo (template) já aprovado pela Meta. Esta receita mostra como listar os modelos disponíveis e enviar um pela API v3.

Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por O que a API v3 faz e como começar.

Objetivo

Enviar um modelo aprovado para um contato fora da janela de 24 horas, pela API.

Pré-requisitos

Tempo estimado

10 minutos.

Caminho de acesso

Chamada direta à API, não é a mesma tela de Atendimentos → Enviar modelo, que é a via manual (veja Enviar um modelo de mensagem (WhatsApp Oficial)).

Passo a passo

  1. Liste os modelos do canal para pegar o id, o language e as variables que ele espera:

    curl "https://api.atende.bot/public/v3/templates?channel=CHANNEL_ID" \
  -H "Authorization: Bearer SEU_TOKEN"

    Cada item traz sendable: true quando o modelo está aprovado e pronto para envio.

    Em canal não oficial (UazAPI/Z-API), esse filtro também devolve os modelos do tenant (que não pertencem a um canal específico e por isso servem para qualquer conversa não oficial).

  2. Envie pelo mesmo endpoint de mensagens, não existe rota própria de template: é POST /public/v3/messages com template em vez de content:

    curl -X POST https://api.atende.bot/public/v3/messages \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-…" \
  -d '{
    "contact": "phone:5511999998888",
    "channel": "CHANNEL_ID",
    "template": "TEMPLATE_ID",
    "params": ["João", "pedido #4821"]
  }'

    params são os valores de {{1}}, {{2}}... do corpo aprovado, na ordem: a contagem precisa bater com a do modelo. contact aceita o uuid do contato ou o prefixo phone: com o telefone em E.164 (sem +), que cria o contato se ainda não existir.

  3. Use Idempotency-Key (um UUID por envio) sempre que o fluxo puder retentar a chamada: a mesma chave com o mesmo corpo devolve a resposta original em vez de reenviar o modelo; com corpo diferente, 409 IDEMPOTENCY_KEY_REUSE.

Resultado esperado

201 com a mensagem criada; o contato recebe o modelo mesmo com a janela de 24h fechada, e a conversa reabre.

Erros comuns

Artigos relacionados

Sincronizar contatos com o seu sistema

Se seu sistema (ERP, planilha, outro CRM) é a fonte da verdade dos seus contatos, você quer mantê-los sincronizados com o AtendeBot nos dois sentidos: seu sistema envia atualizações para cá, e o AtendeBot avisa quando um contato muda por aqui (ex.: um atendente editou o e-mail no atendimento).

Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por O que a API v3 faz e como começar.

Objetivo

Criar ou atualizar contatos pelo telefone a partir do seu sistema, em um contato por vez ou em lote, e receber de volta as mudanças feitas no AtendeBot.

Pré-requisitos

Tempo estimado

15 minutos.

Caminho de acesso

Chamada direta à API: não há tela equivalente no AtendeBot para sincronização em lote vinda de fora.

Passo a passo

  1. Criar ou atualizar um contato pelo telefone, num único contato: use if_exists: "update" para que a mesma chamada funcione tanto na primeira sincronização (cria) quanto nas seguintes (atualiza). O telefone precisa vir com DDI, em E.164:

    curl -X POST https://api.atende.bot/public/v3/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "phone": "5511999998888",
    "email": "maria@exemplo.com",
    "if_exists": "update"
  }'

    Sem if_exists, telefone já cadastrado responde 409 CONFLICT, proteção contra duplicata quando você quer só criar.

  2. Em lote, até 500 contatos por chamada, em POST /contacts/batch (só criação, não aceita if_exists):

    curl -X POST https://api.atende.bot/public/v3/contacts/batch \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "Maria Souza", "phone": "5511999998888" },
    { "name": "João Lima", "phone": "5521988887777" }
  ]'

    A resposta traz meta.partial: true quando algum item falha depois de gravar (ex.: tag inexistente); cada falha aparece em failed, com o índice do item no campo field.

  3. De volta: crie a assinatura do evento contact.updated no formato 3 (o que esta receita espera). Pela tela de Ajustes (API e webhooks → Webhooks) ela já nasce nesse formato: no diálogo, "Formato do payload" fica em v3, e o botão { } ao lado de cada evento abre o envelope de exemplo. Ou pela API:

    curl -X POST https://api.atende.bot/public/v3/webhooks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sincronizar contatos: de volta",
    "url": "https://SEU-ENDPOINT/webhooks/contact-updated",
    "events": [{ "name": "contact.updated" }],
    "secret": "UM_SEGREDO_SEU"
  }'

    A entrega traz data.contact (o contato já carregado: id, name, phone, email, tags...) e data.changed, a lista dos campos que mudaram. Na maioria dos casos você nem precisa buscar de novo; se precisar do contato completo, use GET /public/v3/contacts/{{ $json.data.contact.id }} ou GET /public/v3/contacts/phone:5511999998888 (o prefixo phone: funciona como referência direta).

Resultado esperado

Contato criado ou atualizado a partir do seu sistema; mudanças feitas por aqui chegam de volta pelo webhook contact.updated.

Erros comuns

Artigos relacionados

Enviar um e-mail transacional pela API

Envie um e-mail avulso (código de verificação, confirmação de pedido, aviso de troca de senha) a partir do seu sistema ou do n8n, usando um modelo de e-mail do AtendeBot. Esta receita mostra como pegar o ID do modelo e disparar o envio pela API v3.

🧩 Este recurso faz parte do módulo E-mail. Se ele não aparecer na sua conta, fale com o administrador para ativá-lo. Veja Planos e módulos.

Objetivo

Enviar um e-mail transacional a um destinatário, pela API, a partir de um modelo publicado.

Pré-requisitos

Tempo estimado

10 minutos.

Caminho de acesso

Ajustes → E-mail → Modelos, menu de três pontos do modelo, Usar pela API. O envio em si é uma chamada direta à API.

Passo a passo

  1. Em Ajustes → E-mail → Modelos, abra o menu de três pontos de um modelo transacional publicado e clique em Usar pela API. A janela mostra o ID do modelo (com botão de copiar), as variáveis divididas em Preenchidas pelo contato e Envie em template_data, e um exemplo de curl pronto.

  2. Envie o e-mail:

    curl -X POST https://api.atende.bot/public/v3/emails \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-0b6c-4a1e-9d3a-2c5e7b1a9f00" \
  -d '{
    "template": "TEMPLATE_ID",
    "to": "cliente@exemplo.com",
    "template_data": { "codigo": "482913" }
  }'
    • template: o ID copiado no passo 1.
    • to: o endereço de destino. Em vez dele (ou junto), contact aceita o ID do contato ou phone:+5511999998888 (com código do país).
    • template_data: um objeto com chave e texto, uma chave para cada variável da lista Envie em template_data.

  3. No n8n, use o nó HTTP Request (método POST, a mesma URL, autenticação por header Authorization: Bearer) com esse corpo JSON, montando to e template_data a partir dos dados do fluxo.

  4. Para descobrir os modelos pela API em vez de copiar o ID na tela, chame GET https://api.atende.bot/public/v3/emails/templates (permissão Leitura em E-mails). Cada item traz id, name, category, sendable (só true pode ser enviado), variables (todas as chaves que o modelo publicado usa) e contact_variables (as que o AtendeBot preenche sozinho). Modelos arquivados não aparecem.

  5. Mande sempre o header Idempotency-Key (um UUID por envio): se o fluxo repetir a chamada com a mesma chave, a resposta é a mesma e nenhum segundo e-mail sai.

Onde o envio aparece

O e-mail enviado pela API fica no histórico do contato (aba E-mails e linha do tempo) com a origem API · nome do token, para você saber qual integração o disparou. Se o token for excluído depois, a origem passa a ser só API.

Como as variáveis são preenchidas

Resultado esperado

201 com o e-mail enviado. Em alguns casos a API responde 200 com status suppressed ou failed e um error.code: RECIPIENT_SUPPRESSED, PROVIDER_REJECTED, DELIVERY_UNCERTAIN, ENVIRONMENT_BLOCKED, RENDER_FAILED ou SEND_FAILED. A lista completa de erros (400, 403, 404, 413, 422, 429, 502) está em https://api.atende.bot/public/v3/docs.

Limites e cota

Erros comuns

Artigos relacionados