Skip to main content

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](/books/api-e-integracoes/page/o-que-a-api-v3-faz-e-como-comecar).

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 (Canais e integrações → 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

  • Sintoma: 400 reclamando de pipeline/stage. Solução: envie ao menos um dos dois; enviando os dois, a etapa precisa pertencer àquele funil.
  • Sintoma: cards duplicados para o mesmo contato. Solução: confirme que a checagem por ?contact= está mesmo antes do POST no fluxo.

Artigos relacionados