Comecando

Guia passo a passo para configurar e comecar a usar o MAZAM WABA Connector com a Meta WhatsApp Cloud API oficial.

Pre-requisitos

Antes de comecar, voce precisa de:

Meta Business Account — Conta verificada no Meta Business Manager
WhatsApp Business App — Aplicacao criada no Meta Developers
Phone Number ID — Numero registrado no WhatsApp Business
WABA ID — ID da conta WhatsApp Business
Access Token — System User Token ou OAuth Token
Docker (recomendado) — Para deploy via container

Variaveis de Ambiente

Crie um arquivo .env na raiz do projeto:

Meta Cloud API (obrigatorias)

# Credenciais Meta
META_APP_ID=seu-app-id
META_APP_SECRET=seu-app-secret
META_VERIFY_TOKEN=token-verificacao-webhook
META_API_VERSION=v25.0

# Banco de dados
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/waba_connector

# Redis (buffer de mensagens + idempotencia)
REDIS_URL=redis://localhost:6379/0
MESSAGE_BUFFER_DELAY=8

# Chave de autenticacao da API
API_KEY=sua-api-key-segura

# Admin panel
ADMIN_USER=admin
ADMIN_PASSWORD=sua-senha-segura
ADMIN_JWT_SECRET=seu-jwt-secret

Modulo de Agente IA (opcional)

AGENT_MODULE_URL=http://localhost:8000
AGENT_MODULE_USER=usuario
AGENT_MODULE_PASSWORD=senha
AGENT_TIMEOUT=60

Storage S3 (opcional)

STORAGE_PROVIDER=aws
STORAGE_ENDPOINT=https://s3.us-east-1.amazonaws.com
STORAGE_ACCESS_KEY=sua-access-key
STORAGE_SECRET_KEY=sua-secret-key
STORAGE_BUCKET=meu-bucket

Setup com Docker Compose

A forma mais rapida de rodar todos os servicos:

# Clone o repositorio
git clone <repositorio>
cd waba-connector

# Configure as variaveis de ambiente
cp .env.example .env
# Edite o .env com suas credenciais Meta

# Suba todos os servicos
docker compose up -d

Servicos disponiveis

Servico	URL	Descricao
API (FastAPI)	http://localhost:8200	Backend principal
Admin Panel	http://localhost:3300	Painel de gerenciamento
Documentacao	http://localhost:3400	Este site de docs
Swagger	http://localhost:8200/docs	API interativa

Verifique se o servico esta rodando:

curl http://localhost:8200/health

Resposta esperada (200 OK):

{
  "service": "mazam-waba-connector",
  "version": "1.0.0",
  "status": "healthy"
}

Primeira Instancia

Acesse o Admin Panel em http://localhost:3300
Faca login com suas credenciais admin
Clique em "Nova Instancia"
Preencha: Phone Number ID, WABA ID, Access Token
A instancia sera ativada automaticamente

Primeira Mensagem

curl -X POST "http://localhost:8200/send/text" \
  -H "Authorization: Bearer sua-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "body": "Ola! Teste via MAZAM WABA Connector + Meta Cloud API."
  }'

Configurar Webhook

Para receber mensagens, configure o webhook no Meta Developers:

Acesse Meta Developers > Seu App > WhatsApp > Configuracao
Webhook URL: https://seu-dominio.com/webhooks/whatsapp
Verify Token: valor de META_VERIFY_TOKEN no seu .env
Inscreva-se nos campos: messages

Proximos Passos

Referencia da API

Documentacao completa dos endpoints

Health Check

Configure probes de monitoramento

Este guia foi útil?

Última atualização: 7 de abril de 2026

Comecando

Referencia da API

Health Check

On this page