Integração Chatbot WhatsApp + Bitrix24

Visão Geral

Este projeto implementa um chatbot integrado entre WhatsApp (WPPConnect), permitindo que usuários consultem dados do CRM, recebam notificações e executem ações diretamente pelo WhatsApp.

Arquitetura

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│  WhatsApp   │ ───> │   Webhook    │ ───> │  Bitrix24   │
│    API      │ <─── │   Handler    │ <─── │     API     │
└─────────────┘      └──────────────┘      └─────────────┘

Configuração

1. Credenciais Bitrix24

Obtenha suas credenciais no painel administrativo do Bitrix24:

BITRIX_DOMAIN=https://sua-empresa.bitrix24.com.br
BITRIX_WEBHOOK_TOKEN=k7m9n2p4q6r8s0t1u3v5w7...
BITRIX_USER_ID=1

2. Credenciais WhatsApp Business

Configure sua conta no Meta Business:

WHATSAPP_PHONE_NUMBER_ID=102429845860943
WHATSAPP_ACCESS_TOKEN=EAALxY9ZB8gM4BO...
WHATSAPP_BUSINESS_ACCOUNT_ID=123456789
WHATSAPP_WEBHOOK_VERIFY_TOKEN=meu_token_secreto_123

3. Webhooks

Configurar Webhook no Bitrix24

1. Acesse: Aplicações > Webhooks > Webhook de Entrada
2. Configure os eventos:
   • ONCRMDEALADD (novo negócio)
   • ONCRMDEALUPDATE (atualização de negócio)
   • ONCRMCONTACTADD (novo contato)
   • ONTASKCOMMENTADD (comentário em tarefa)
3. URL do webhook: https://seu-dominio.com/api/webhook/bitrix24

Configurar Webhook no WhatsApp

1. Acesse Meta for Developers
2. Configure o webhook:
   • URL: https://seu-dominio.com/api/webhook/whatsapp
   • Token de verificação: seu token secreto
3. Inscreva-se nos campos: messages, message_status

Estrutura do Código

Webhook Bitrix24 (/app/api/webhook/bitrix24/route.ts)

Recebe eventos do Bitrix24 e processa:

// Exemplo de payload recebido
{
  "event": "ONCRMDEALADD",
  "data": {
    "FIELDS": {
      "ID": "123",
      "TITLE": "Novo Negócio",
      "STAGE_ID": "NEW",
      "OPPORTUNITY": "15000.00"
    }
  }
}

API de Testes (/app/api/test/bitrix24/route.ts)

Endpoints para testar a integração:

# Status da integração
GET /api/test/bitrix24?action=status

# Listar negócios
GET /api/test/bitrix24?action=deals

# Listar contatos
GET /api/test/bitrix24?action=contacts

# Testar webhook
GET /api/test/bitrix24?action=webhook_test

Métodos da API Bitrix24

Listar Negócios

async function listDeals() {
  const response = await fetch(
    `${BITRIX_DOMAIN}/rest/${BITRIX_USER_ID}/${BITRIX_WEBHOOK_TOKEN}/crm.deal.list.json`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        order: { DATE_CREATE: 'DESC' },
        filter: { STAGE_ID: 'NEW' },
        select: ['ID', 'TITLE', 'OPPORTUNITY', 'STAGE_ID']
      })
    }
  )
  return await response.json()
}

Criar Contato

async function createContact(name, phone, email) {
  const response = await fetch(
    `${BITRIX_DOMAIN}/rest/${BITRIX_USER_ID}/${BITRIX_WEBHOOK_TOKEN}/crm.contact.add.json`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        fields: {
          NAME: name,
          PHONE: [{ VALUE: phone, VALUE_TYPE: 'WORK' }],
          EMAIL: [{ VALUE: email, VALUE_TYPE: 'WORK' }]
        }
      })
    }
  )
  return await response.json()
}

Atualizar Negócio

async function updateDeal(dealId, fields) {
  const response = await fetch(
    `${BITRIX_DOMAIN}/rest/${BITRIX_USER_ID}/${BITRIX_WEBHOOK_TOKEN}/crm.deal.update.json`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        id: dealId,
        fields: fields
      })
    }
  )
  return await response.json()
}

Envio de Mensagens WhatsApp

async function sendWhatsAppMessage(phone, message) {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/${WHATSAPP_PHONE_NUMBER_ID}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${WHATSAPP_ACCESS_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        messaging_product: 'whatsapp',
        to: phone,
        type: 'text',
        text: { body: message }
      })
    }
  )
  return await response.json()
}

Fluxo de Notificações

1. Novo Negócio Criado

Bitrix24 → Webhook → Processa dados → WhatsApp

Quando um negócio é criado no Bitrix24:

1. Webhook recebe evento ONCRMDEALADD
2. Sistema extrai dados do negócio
3. Formata mensagem personalizada
4. Envia notificação via WhatsApp ao responsável

2. Consulta via WhatsApp

WhatsApp → Webhook → API Bitrix24 → Resposta → WhatsApp

Quando usuário envia mensagem:

1. WhatsApp envia para webhook
2. Sistema interpreta comando
3. Faz requisição à API Bitrix24
4. Formata e retorna dados via WhatsApp

Comandos Disponíveis

Comando	Descrição	Exemplo
status	Status do sistema	"qual o status?"
negócios	Lista negócios	"meus negócios"
contatos	Lista contatos	"listar contatos"
tarefas	Lista tarefas	"minhas tarefas"
criar negócio	Cria novo negócio	"criar negócio Cliente X"
relatório	Gera relatório	"gerar relatório mensal"

Modo de Teste

O sistema está configurado em modo de teste com dados simulados. Para ativar produção:

1. Configure as variáveis de ambiente reais
2. Remova o painel de teste da interface
3. Ative os webhooks reais nas plataformas
4. Execute testes completos antes de disponibilizar

Logs e Monitoramento

Todos os eventos são registrados com prefixo [v0]:

console.log('[v0] Webhook recebido:', eventData)
console.log('[v0] Consultando Bitrix24 API')
console.log('[v0] Enviando notificação WhatsApp')

Segurança

Validação de Webhooks

// Verificar assinatura do webhook
function verifyWebhookSignature(payload, signature) {
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex')
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

Rate Limiting

Implemente rate limiting para evitar abuso:

// Limite de 10 requisições por minuto por usuário
const rateLimit = {
  windowMs: 60 * 1000,
  max: 10
}

Troubleshooting

Webhook não está recebendo eventos

1. Verifique se a URL está acessível publicamente
2. Confirme que os eventos estão configurados no Bitrix24
3. Teste com ngrok em desenvolvimento

Mensagens WhatsApp não enviadas

1. Verifique o token de acesso
2. Confirme que o número está verificado
3. Verifique os logs da Meta for Developers

Erros na API Bitrix24

1. Verifique as credenciais
2. Confirme as permissões do webhook
3. Teste os endpoints manualmente

Referências

• Bitrix24 REST API
• WhatsApp Business API
• Meta Webhooks

Suporte

Para dúvidas e suporte:

• Documentação Bitrix24: https://helpdesk.bitrix24.com/
• WhatsApp Business: https://business.whatsapp.com/
• Issues: Abra uma issue no repositório

---

Versão: 1.0.0
Última atualização: Janeiro 2026
Status: Em modo de teste