Guia: Conectar o Agente SDR no WhatsApp via CRM Avalanche

Antes de colocar a mao na massa, entenda o caminho completo que uma mensagem percorre. Sao quatro atores: o lead (a pessoa que manda mensagem), o CRM Avalanche (recebe e organiza tudo), o Workflow (a automacao que avisa o agente) e o agente SDR (o programa com IA que roda no seu servidor e responde).

O que e "painel" e o que e "tecnico"

Este guia mistura duas naturezas de trabalho. Deixar isso claro evita confusao:

Voce ja chega com duas coisas prontas. O resto voce vai montar ao longo do guia. Esta e a lista completa.

Voce ja tem

• Conta do CRM Avalanche do cliente (a sub-account dele criada).
• Agente SDR treinado: o codigo do agente mais o dossie de treinamento pronto. Ainda nao esta rodando nem exposto na internet.

Voce vai precisar montar

Dados que o cliente precisa te passar

• Nome do agente (como ele vai se apresentar).
• Lista de produtos com nome, preco, o que inclui e link de venda.
• Tom de voz desejado (caloroso, tecnico, amigavel, etc.).
• Nomes pra bloquear (socios, familia, funcionarios que nao devem receber mensagem do agente).
• A chave API (PIT) e o Location ID do CRM Avalanche.

Esta e a etapa mais tecnica do guia. O objetivo aqui e simples de descrever: deixar o agente rodando sempre, num servidor, com um endereco publico e seguro (HTTPS) que o CRM consiga chamar. No fim, voce vai ter a URL do webhook, algo como https://agente-CLIENTE.seudominio.com.br/webhook. Os comandos estao prontos, e so copiar e colar em ordem.

3.1 Entrar no servidor e instalar as dependencias

Conecte no servidor por SSH (usando o IP que voce anotou) e rode os comandos abaixo. Eles atualizam o sistema e instalam Python, Node, o PM2 (que mantem o agente sempre ligado) e o PostgreSQL (banco de dados).

# Atualizar o sistema
sudo apt update && sudo apt upgrade -y

# Python 3.10+
sudo apt install python3 python3-pip python3-venv -y

# Node.js 18+ (necessario pro PM2)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo bash -
sudo apt install nodejs -y

# PM2 (mantem o agente rodando sempre)
sudo npm install -g pm2

# PostgreSQL (banco de dados do agente)
sudo apt install postgresql postgresql-contrib -y
sudo systemctl enable postgresql
sudo systemctl start postgresql

3.2 Criar o banco de dados

O agente guarda as conversas num banco. Troque meuagente e SENHA_SEGURA pelos seus valores.

sudo -u postgres createuser meuagente
sudo -u postgres createdb agente_db -O meuagente
sudo -u postgres psql -c "ALTER USER meuagente PASSWORD 'SENHA_SEGURA';"

3.3 Instalar o Caddy (o que cria o endereco seguro)

O Caddy e um "porteiro" que recebe as chamadas da internet no seu dominio e repassa pro agente. Ele tambem cria o cadeado HTTPS sozinho, de graca.

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy -y

3.4 Instalar os pacotes Python do agente e a chave da IA

# Bibliotecas que o agente usa
pip install httpx psycopg2-binary fastapi uvicorn claude-agent-sdk openai-whisper

# Chave da Anthropic (troque pela sua). Fica salva entre sessoes.
echo 'export ANTHROPIC_API_KEY="sk-ant-SUA_CHAVE_AQUI"' >> ~/.bashrc
source ~/.bashrc

3.5 Colocar o agente pra rodar sempre (PM2)

O agente e um programa Python (FastAPI + Claude Agent SDK). Coloque os arquivos dele na pasta do projeto (o codigo do agente e o config-N.json da secao 4). O N e o numero do agente (ex: 3). Cada agente roda numa porta propria (ex: 3501).

# Iniciar o agente com PM2 (troque o caminho e o numero 3)
pm2 start /opt/seu-projeto/scripts/agents/template.py \
    --name sdr-agent-3 \
    --interpreter python3 \
    -- 3

# Salvar pra reiniciar sozinho se o servidor reiniciar
pm2 save

# Configurar o auto-start no boot (rode o comando que ele mostrar)
pm2 startup

Confira se subiu. O health check deve responder com os dados do agente:

pm2 status
curl localhost:3501/health
# Esperado: {"status":"ok","agent":"...","company":"...","port":3501}

3.6 Apontar o dominio pro servidor (DNS no Cloudflare)

Agora dizemos pra internet que o subdominio do webhook mora no seu servidor. No painel do Cloudflare, no seu dominio:

1. Va em DNS → Add Record.
2. Type: A
3. Name: o subdominio (ex: agente-cliente para agente-cliente.seudominio.com.br).
4. Content: o IP do seu servidor (ex: IP_DO_SERVIDOR).
5. Proxy: ON (nuvem laranja).
6. Salve.

3.7 Configurar o Caddy com o dominio (fecha o HTTPS)

Edite o arquivo do Caddy pra ligar o dominio a porta do agente.

sudo nano /etc/caddy/Caddyfile

Conteudo (cada agente aponta pra sua porta):

# Webhook do agente SDR (uma porta por agente)
agente-cliente.seudominio.com.br {
    reverse_proxy localhost:3501
}

Recarregue o Caddy. Ele gera o certificado HTTPS sozinho (Let's Encrypt) em poucos segundos.

sudo systemctl reload caddy

# Testar o HTTPS de fora (deve responder status ok)
curl https://agente-cliente.seudominio.com.br/health

Todo agente le um arquivo config-N.json (onde N e o numero do agente). E nesse arquivo que voce liga o agente ao canal certo e ao CRM do cliente. Os campos que importam pra conexao com WhatsApp sao tres: channel_type, crm_api_key e crm_location_id.

Exemplo de config para WhatsApp

Note o channel_type como WhatsApp. Este e o exemplo pronto pra ajustar (troque os placeholders pelos valores reais).

{
  "id": 3,
  "name": "NomeDoAgente",
  "company": "Cliente | Nicho",
  "port": 3501,
  "personality": "Voce e a [NOME], do time de [EMPRESA]. Tom caloroso. NUNCA pareca vendedor agressivo. NUNCA mencione precos. Se perguntarem o preco, diga: confere os detalhes no site! E mande o link.",
  "products": "Curso A (R$297), Curso B (R$497), Mentoria (R$1997).",
  "links": "https://produto.seudominio.com.br/?src=nome-agente",
  "blocked_names": "socio1,familiar1",
  "crm_api_key": "pit-SUA_CHAVE_AQUI",
  "crm_location_id": "SEU_LOCATION_ID_AQUI",
  "calendar_id": "",
  "spin_flow": "FLUXO SPIN SELLING (4 ETAPAS): ETAPA 1 - RAPPORT... ETAPA 4 - OFERTA: mande o link UMA UNICA VEZ.",
  "channel_type": "WhatsApp",
  "receive_method": "webhook",
  "send_method": "api",
  "send_webhook_url": ""
}

O agente precisa de duas credenciais pra conversar com o CRM: a chave de acesso (PIT) e o Location ID. Ambas ficam dentro da conta do cliente.

5.1 Criar a chave PIT (Private Integration Token)

1. Acesse a sub-account do cliente no CRM Avalanche.
2. Va em Settings (a engrenagem, canto inferior esquerdo).
3. Abra Business Profile.
4. Role ate API Keys (ou Integrations).
5. Clique em Private Integration Token.
6. De permissao de Contacts (read/write), Conversations (read/write) e Calendars (read).
7. Copie o token. O formato e pit-SUA_CHAVE_AQUI (tipo pit-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

5.2 Encontrar o Location ID

1. Ainda na sub-account, olhe a URL do navegador: o Location ID e o codigo alfanumerico que aparece nela.
2. Alternativa: Settings → Business Profile → Location ID.
3. Copie e cole no config-N.json (campo crm_location_id).

Existem dois jeitos de ter WhatsApp dentro do CRM. Escolha um. Ele determina o channel_type do agente (secao 4) e o filtro do Workflow (secao 7).

Opcao A: WhatsApp Oficial (Meta / WhatsApp Business API)

E o oficial, homologado pela Meta. Mais confiavel e estavel, mas tem a regra das 24 horas.

Pre-requisitos

• Numero de WhatsApp Business API configurado no CRM (via Meta Business Suite).
• Numero verificado e aprovado pela Meta.

Passos no CRM

1. Va em Settings → Phone Numbers (ou WhatsApp).
2. Configure o numero do WhatsApp Business API da Meta.
3. No Workflow (secao 7), use o filtro Reply Channel = WhatsApp.
4. No config do agente, use "channel_type": "WhatsApp".

Opcao B: WhatsApp nao oficial (LC Phone)

E o numero do proprio CRM. Mais simples de ligar (ja vem no sub-account), sem regra de 24h nem template, mas menos confiavel (pode ser bloqueado pela Meta).

Pre-requisitos

• Numero LC Phone configurado no CRM (normalmente ja vem no sub-account).

Passos no CRM

1. O numero LC Phone geralmente ja esta ativo no sub-account.
2. No Workflow (secao 7), use o filtro Reply Channel = SMS (ou All).
3. No config do agente, use "channel_type": "SMS".

O Workflow e a peca que liga o CRM ao seu agente. Toda vez que um lead responde, ele dispara e envia os dados da mensagem pra URL do webhook (a que voce montou na secao 3). Sem ele, o agente nunca fica sabendo que chegou mensagem.

7.1 Criar o Workflow

1. Na sub-account do cliente, va em Automation (menu lateral).
2. Clique em Workflows.
3. Create Workflow → Start from scratch.
4. De um nome claro, ex: Webhook Agente SDR - WhatsApp.

7.2 Configurar o Trigger (o gatilho)

1. Clique no bloco de trigger.
2. Selecione Customer Replied.
3. Em Filters, configure o Reply Channel conforme o canal:
   • WhatsApp Oficial: WhatsApp
   • WhatsApp nao oficial (LC Phone): SMS/Phone ou All

7.3 Configurar a Action (o webhook)

1. Clique no + pra adicionar uma acao.
2. Selecione Webhook (ou Custom Webhook).
3. Preencha:
   • Method: POST
   • URL: https://agente-cliente.seudominio.com.br/webhook (a sua URL da secao 3)
   • Headers: Content-Type: application/json
   • Body (JSON): exatamente o bloco abaixo

Este e o corpo do webhook. Os campos entre chaves duplas sao variaveis que o CRM preenche sozinho com os dados do contato e da mensagem:

{
  "contact_id": "{{contact.id}}",
  "full_name": "{{contact.full_name}}",
  "first_name": "{{contact.first_name}}",
  "message": {
    "body": "{{message.body}}"
  }
}

4. Clique em Save.
5. No canto superior direito, ative o Workflow (toggle ON / Publish).

Depois de pensar, o agente devolve a resposta chamando a API do CRM. Isso ja esta pronto dentro do codigo do agente, mas e importante voce entender como funciona, porque e aqui que mora o famoso erro 422.

8.1 O endpoint

POST https://services.seucrm.com.br/conversations/messages

8.2 Os headers

A chamada leva a chave PIT (Bearer) e a versao da API. A Version tem que ser exatamente essa.

Authorization: Bearer pit-SUA_CHAVE_AQUI
Version: 2021-07-28
Content-Type: application/json

8.3 O corpo (body)

O campo type e o coracao da coisa: e ele que diz por qual canal a resposta sai. Se estiver errado, o CRM recusa com erro 422.

{
  "type": "WhatsApp",
  "contactId": "ID_DO_CONTATO",
  "message": "Texto da mensagem"
}

8.4 Tabela de tipos de canal (critico)

Use o type certo pro canal. Este e o valor que o campo channel_type do config vira na hora de enviar.

Com tudo montado, hora de simular um lead de verdade e ver o agente responder sozinho.

9.1 O teste principal

1. De outro numero (nao o do cliente), mande uma mensagem no WhatsApp do cliente, ex: oi, queria saber sobre o curso.
2. No servidor, acompanhe os logs pra ver a mensagem chegar:

pm2 logs sdr-agent-3
# Esperado: linha de entrada (IN ...) e depois o envio (OK Msg 1/1 to ...)

3. Aguarde. E normal levar de 20 a 25 segundos (o agente espera juntar mensagens e simula tempo de digitacao).
4. Confirme que a resposta chegou no WhatsApp de quem mandou.

9.2 Testar o webhook sozinho (sem depender do CRM)

Pra saber se o agente esta recebendo bem, voce pode simular uma chamada do CRM direto pela URL publica:

curl -X POST https://agente-cliente.seudominio.com.br/webhook \
  -H 'Content-Type: application/json' \
  -d '{"contact_id":"test","full_name":"Teste","message":{"body":"oi"}}'

Se o agente responder {"success": true}, o webhook esta recebendo. Se der erro de conexao, revise a secao 3 (Caddy, DNS, PM2).

9.3 Checklist: se nao funcionar, verifique nesta ordem

• Workflow ativo? No CRM, confira se o toggle esta ON (publicado).
• Filtro de canal certo? WhatsApp Oficial usa WhatsApp; LC Phone usa SMS ou All.
• URL do webhook certa? Tem que ser a sua e terminar em /webhook.
• channel_type certo no config? Tem que casar com o canal real (senao da 422 na resposta).
• Agente online? pm2 status deve mostrar "online". Health: curl localhost:3501/health.
• Chave da IA configurada? Se recebe mas nao responde, cheque ANTHROPIC_API_KEY e os logs.
• Erro 403? A PIT expirou ou nao tem permissao de Contacts + Conversations.
• Erro 422? O type/channel_type nao bate com o canal do lead.

Os problemas que mais aparecem e como resolver cada um.

Erro 422 ao enviar a resposta

O canal do type nao bate com o canal do lead. Mensagens tipicas: "Contact has no Instagram id" (voce usou IG mas o lead veio de outro canal) ou "Contact has no phone".

• Solucao: ajuste o channel_type no config-N.json pro canal correto (WhatsApp ou SMS) e reinicie o agente (pm2 restart sdr-agent-3).

Erro 403 na API do CRM

A chave PIT expirou ou nao tem permissao suficiente.

• Confira em Settings → API Keys se a chave esta ativa.
• Garanta permissao de Contacts + Conversations.
• Se preciso, gere uma nova PIT e atualize o config-N.json.

Agente respondendo no canal errado

• Cada canal precisa de um agente separado (um pra WhatsApp, outro pra Instagram).
• Cheque o channel_type: WhatsApp, SMS ou IG.
• Nunca use o mesmo agente pra dois canais diferentes.

Mensagem nao chega no agente

• Workflow ATIVO no CRM? (toggle ON).
• Filtro de canal certo?
• Teste a URL direto com o curl da secao 9.2.
• Caddy (reverse proxy) e DNS funcionando?

Agente recebe mas nao responde

• Veja os logs: pm2 logs sdr-agent-3 --lines 50.
• ANTHROPIC_API_KEY configurada?
• Pode ser limite de uso momentaneo da IA. Aguarde e tente de novo.

Resposta demora muito

• O tempo padrao e ~20 a 25 segundos (8s pra juntar mensagens + 8s simulando digitacao + a IA pensando). Isso e normal.
• Se passar de 1 minuto, procure erros nos logs.

Mensagens duplicadas

• Confira se nao ha mais de um Workflow ativo pro mesmo gatilho.
• O CRM pode estar disparando o webhook mais de uma vez.