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

Token de API com escopos cards:write e cards:read: veja Gerar tokens de API para integrações.
Um webhook cadastrado para o evento message.received apontando para o n8n: passo 1 abaixo (o que é um webhook: Configurar webhooks para sistemas externos).
O id do funil (pipeline) e da etapa (stage) onde o card deve entrar.

Tempo estimado

15 minutos.

Caminho de acesso

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

Passo a passo

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"] } }]
```

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"

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.

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.

Abrir um card no CRM quando chega uma mensagem

Objetivo

Pré-requisitos

Tempo estimado

Caminho de acesso

Passo a passo

Resultado esperado

Erros comuns

Artigos relacionados