Pular para conteúdo

Configuracao Chatwoot + Pontifex IA

Guia completo para integrar o Chatwoot com o agente Pontifex IA.

Arquitetura

┌─────────────┐    webhook     ┌──────────────┐    OpenAI API    ┌───────────┐
│  Chatwoot   │ ─────────────> │ Pontifex IA  │ <──────────────> │  OpenAI   │
│  (Rails)    │ <───────────── │   (FastAPI)  │    (GPT-4o)      │           │
└─────────────┘   API response └──────────────┘                  └───────────┘
     :3000                           :8000

Pre-requisitos

  • Docker e Docker Compose instalados
  • Chatwoot rodando (self-hosted)
  • Chave de API da OpenAI

Passo 1: Subir os Servicos

cd /root/pontifex-ia

# Criar volumes externos (apenas primeira vez)
docker volume create chatwoot_postgres
docker volume create chatwoot_redis
docker volume create chatwoot_storage

# Subir servicos
docker compose -f docker-compose.production.yml up -d postgres redis

# Aguardar banco iniciar
sleep 10

# Inicializar banco do Chatwoot (apenas primeira vez)
docker compose -f docker-compose.production.yml run --rm rails bundle exec rails db:chatwoot_prepare

# Subir todos os servicos
docker compose -f docker-compose.production.yml up -d

Passo 2: Criar Conta Admin no Chatwoot

  1. Acesse no navegador: http://SEU_IP:3000
  2. Na tela de boas-vindas, clique em Create New Account
  3. Preencha o formulario:
  4. Full Name: Seu nome (ex: Administrador)
  5. Email: Seu email de administracao
  6. Password: Senha forte
  7. Account Name: Nome da organizacao (ex: Instituto FD)
  8. Clique em Sign Up
  9. Voce sera redirecionado para o painel do Chatwoot
  10. Se SMTP estiver configurado, confirme o email antes de prosseguir
  11. Se nao, o acesso ja estara liberado

Passo 3: Criar API Channel Inbox

O API Channel e o canal que conecta o Pontifex IA ao Chatwoot. Atraves dele, o Chatwoot envia mensagens recebidas (via webhook) para o agente processar e responder.

3.1 Acessar configuracao de Inboxes

  1. No painel do Chatwoot, olhe a barra lateral esquerda
  2. Clique no icone de engrenagem (Settings) — fica na parte inferior da barra lateral
  3. No menu que abre, clique em Inboxes (na coluna da esquerda, sob "Settings")
  4. Clique no botao "+ Add Inbox" (canto superior direito)

3.2 Selecionar tipo de canal

  1. Na tela "Choose a channel", voce vera varios icones de canais (Website, Facebook, Twitter, etc.)
  2. Selecione API — e o icone com as chaves { }, geralmente na segunda linha de opcoes
  3. Clique nele para prosseguir

3.3 Configurar o canal API

Na tela de configuracao, preencha:

Campo Valor Descricao
Channel Name Pontifex Bot Nome que aparecera no Chatwoot
Webhook URL http://pontifex-api:8000/webhooks/chatwoot Endereco para onde o Chatwoot envia as mensagens

IMPORTANTE: A Webhook URL usa o nome do container Docker (pontifex-api), nao localhost, pois ambos os servicos estao na mesma rede Docker interna.

  1. Clique em Create API Channel

3.4 Adicionar agentes ao Inbox

  1. Na proxima tela, voce pode adicionar agentes (usuarios humanos) que terao acesso a esse inbox
  2. Selecione o seu usuario admin e outros atendentes que precisarem
  3. Clique em Add Agents

3.5 Anotar o Inbox ID

  1. Apos a criacao, voce sera redirecionado para a tela de configuracao do inbox
  2. Olhe a URL do navegador — ela tera o formato: http://SEU_IP:3000/app/accounts/1/settings/inboxes/X
  3. O numero X no final e o Inbox ID — anote-o, sera usado no credentials.toml

Passo 4: Obter API Access Token

O token de acesso permite que o Pontifex IA envie mensagens de volta ao Chatwoot.

  1. Na barra lateral esquerda do Chatwoot, olhe a parte inferior
  2. Clique no seu avatar (icone do usuario, canto inferior esquerdo)
  3. No menu que abre, clique em Profile Settings
  4. Na pagina de perfil, role a pagina para baixo
  5. Localize a secao "Access Token" — ela mostra um token longo (hash alfanumerico)
  6. Clique no token ou no botao de copiar ao lado para copiar
  7. Cole este token no campo api_token do credentials.toml

IMPORTANTE: Guarde este token em local seguro. Ele da acesso total a conta via API.

Passo 5: Configurar Credenciais

Opcao A: Via GitHub Secrets (Producao)

Configure o secret CREDENTIALS_TOML no GitHub com:

[openai]
api_key = "sk-proj-SUA-CHAVE-OPENAI"

[chatwoot]
api_url = "http://chatwoot-rails:3000"
api_token = "SEU_ACCESS_TOKEN_AQUI"
account_id = 1
inbox_id = 1

Opcao B: Manualmente no VPS

mkdir -p /root/pontifex-ia/.secrets

cat > /root/pontifex-ia/.secrets/credentials.toml << 'EOF'
[openai]
api_key = "sk-proj-SUA-CHAVE-OPENAI"

[chatwoot]
api_url = "http://chatwoot-rails:3000"
api_token = "SEU_ACCESS_TOKEN_AQUI"
account_id = 1
inbox_id = 1
EOF

chmod 600 /root/pontifex-ia/.secrets/credentials.toml

Passo 6: Reiniciar Pontifex API

docker compose -f docker-compose.production.yml restart pontifex-api

Verificar logs:

docker logs pontifex-api --tail 50

Passo 7: Configurar Webhook no Chatwoot

O webhook permite que o Chatwoot envie eventos (novas mensagens, etc.) para o Pontifex IA processar automaticamente.

7.1 Webhook do Inbox (API Channel)

Este webhook ja foi configurado no Passo 3 ao criar o API Channel Inbox. A URL deve apontar para o endpoint interno do Pontifex:

http://pontifex-api:8000/webhooks/chatwoot

Nota: Use o nome do container (pontifex-api) pois ambos estao na mesma rede Docker.

7.2 Webhook Global do Chatwoot (Alternativo)

Alem do webhook do inbox, voce pode configurar um webhook global:

  1. Acesse o Chatwoot em http://SEU_IP:3000
  2. Va em Settings (engrenagem) > Integrations > Configure (ao lado de Webhooks)
  3. Clique em Add new webhook
  4. Configure:
Campo Valor
URL http://pontifex-api:8000/webhooks/chatwoot
Events Selecione message_created
  1. Clique em Add Webhook

7.3 Verificar Webhook

Para confirmar que o webhook esta funcionando:

# Verificar logs do Pontifex em tempo real
docker logs pontifex-api -f

# Enviar uma mensagem no inbox e observar os logs
# Voce deve ver uma entrada como:
# INFO: Webhook recebido - event: message_created

7.4 Troubleshooting de Webhook

Problema Solucao
Webhook nao e recebido Verificar se a URL usa o nome do container (pontifex-api) e nao localhost
Erro de conexao Verificar se ambos containers estao na mesma rede: docker network inspect pontifex-ia_pontifex-network
Resposta nao aparece Verificar se api_token, account_id e inbox_id estao corretos no credentials.toml
Mensagem duplicada Certificar que nao ha webhook global E webhook de inbox apontando para a mesma URL

Passo 8: Testar Integracao

Teste 1: Health Check

curl http://localhost:8000/health
# {"status":"healthy"}

Teste 2: Criar Contato e Conversa via API

# Substituir TOKEN pelo seu API Access Token

# Criar contato
curl -X POST "http://localhost:3000/api/v1/accounts/1/contacts" \
  -H "api_access_token: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": 1, "name": "Teste", "phone_number": "+5511999999999"}'

# Criar conversa (use o source_id retornado)
curl -X POST "http://localhost:3000/api/v1/accounts/1/conversations" \
  -H "api_access_token: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": 1, "contact_id": 1, "source_id": "SOURCE_ID"}'

# Enviar mensagem (simula cliente)
curl -X POST "http://localhost:3000/api/v1/accounts/1/conversations/1/messages" \
  -H "api_access_token: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Ola, quero informacoes sobre o curso", "message_type": "incoming"}'

Teste 3: Verificar Webhook

# Ver logs do Pontifex
docker logs pontifex-api -f

Voce deve ver: - Webhook recebido - Processamento da mensagem - Resposta enviada

Variaveis de Configuracao

Variavel Descricao Exemplo
chatwoot_api_url URL interna do Chatwoot http://chatwoot-rails:3000
chatwoot_api_token Access Token do usuario abc123...
chatwoot_account_id ID da conta 1
chatwoot_inbox_id ID do inbox API 1
chatwoot_webhook_secret Secret para validar webhooks (opcional) meu-secret
chatwoot_human_team_id ID do time para handoff (opcional) 1

Handoff para Humano

O agente pode transferir a conversa para um atendente humano incluindo [HANDOFF] na resposta.

Quando isso acontece: 1. O texto [HANDOFF] e removido da mensagem 2. A conversa muda para status open 3. Se human_team_id estiver configurado, atribui ao time

Troubleshooting

Webhook nao e recebido

  1. Verificar se o callback URL esta correto no inbox
  2. Verificar se os containers estao na mesma rede: 
    docker network inspect pontifex-ia_pontifex-network

Erro 401 ao enviar mensagem

  1. Verificar se o api_token esta correto
  2. Gerar novo token no Chatwoot

Resposta nao aparece

  1. Verificar logs do pontifex-api
  2. Verificar se account_id e inbox_id estao corretos
  3. Testar API manualmente: 
    curl -X POST "http://localhost:3000/api/v1/accounts/1/conversations/1/messages" \
  -H "api_access_token: TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Teste manual", "message_type": "outgoing"}'

Banco de dados vazio apos restart

Verificar se os volumes externos existem: 

docker volume ls | grep chatwoot

Se nao existirem, criar antes de subir os containers.

Backups

Backups automaticos sao criados em /root/backups/ a cada deploy.

Backup manual:

docker exec chatwoot-postgres pg_dump -U postgres chatwoot > backup_$(date +%Y%m%d).sql

Restaurar:

cat backup_20260129.sql | docker exec -i chatwoot-postgres psql -U postgres chatwoot

Checklist de Configuracao

  • [ ] Chatwoot rodando (http://IP:3000)
  • [ ] Conta admin criada
  • [ ] API Channel Inbox criado
  • [ ] Webhook URL configurado: http://pontifex-api:8000/webhooks/chatwoot
  • [ ] API Access Token obtido
  • [ ] credentials.toml configurado com todas as chaves
  • [ ] Pontifex API rodando e healthy
  • [ ] Teste de mensagem funcionando