Integração em produção

Este guia apresenta o fluxo normal de produção para uma implementação do WaGo. O usuário executa o binário do WaGo em seu servidor e sua própria aplicação realiza chamadas para a API HTTP.

Arquitetura

Your app or dashboard
  -> WaGo HTTP API
  -> WhatsApp connection
  -> WhatsApp users and groups

WaGo webhook
  -> Your backend webhook receiver
  -> Your database, jobs, CRM, inbox, or automation

Mantenha o WaGo e sua aplicação separados:

Parte	Responsabilidade
WaGo	Sessão do WhatsApp, leitura de QR code, envio, recebimento, mídia, chamadas, webhooks.
Seu backend	Login do usuário, permissões, propriedade do token, regras de negócio, banco de dados, faturamento, processamento de webhooks.
Seu frontend	UI de status da sessão, exibição do QR code, UI de caixa de entrada, formulários de envio, UI de chamadas.

Passo 1: Armazene o token do WaGo em sua aplicação

Cada conta do WhatsApp conectada utiliza um token de sessão do WaGo. Sua aplicação deve mapear esse token para seu próprio usuário, equipe, workspace ou cliente. Se o token ainda não existir, crie-o com POST /session/init a partir de um backend confiável. Veja Criar um token para o fluxo admin completo. Exemplo de estrutura de banco de dados:

Campo	Exemplo
`workspace_id`	`workspace_123`
`wago_token`	`customer-token-1`
`wago_jid`	`[email protected]`
`webhook_url`	`https://app.example.com/wago/webhook`
`connected`	`true`
`logged_in`	`true`

Não exponha seu admintoken ao frontend. Se o seu produto cria tokens do WaGo para usuários, faça isso a partir do seu backend.

Passo 2: Configure os webhooks

Defina a URL do webhook para o token:

curl -X POST http://localhost:1337/webhook \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "WebhookURL": "https://app.example.com/wago/webhook"
  }'

Em seguida, conecte-se com os tipos de eventos que sua aplicação precisa:

curl -X POST http://localhost:1337/session/connect \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "Subscribe": ["Message", "ReadReceipt", "Presence", "ChatPresence", "Call", "LoggedOut"],
    "Immediate": true,
    "Phone": ""
  }'

Use ["All"] ao criar a primeira versão. Reduza a lista quando sua aplicação estiver estável.

Passo 3: Exiba o status da leitura (scan)

Seu frontend pode realizar polling:

curl -H "token: YOUR_TOKEN" \
  http://localhost:1337/session/status

Use estes campos:

Campo	Significado
`Connected`	O WaGo possui uma conexão ativa com o WhatsApp.
`LoggedIn`	O dispositivo foi lido e autenticado.
`Jid`	A conta do WhatsApp conectada. Armazene-a após a leitura.
`Events`	Tipos de eventos inscritos.

Se a sessão não estiver logada, busque o QR code:

curl -H "token: YOUR_TOKEN" \
  http://localhost:1337/session/qr

Renderize o QRCode como uma imagem em sua UI.

Passo 4: Envie uma mensagem

curl -X POST http://localhost:1337/send/text \
  -H "Content-Type: application/json" \
  -H "token: YOUR_TOKEN" \
  -d '{
    "Phone": "15551234567",
    "Body": "Hello from WaGo"
  }'

Armazene o ID da mensagem retornado. Você precisará dele para confirmações de leitura, status da mensagem, reações, edições e operações de exclusão.

Passo 5: Receba mensagens

Seu webhook recebe dados de formulário:

Campo do formulário	Uso
`token`	Localize o cliente/sessão em seu banco de dados.
`jsonData`	Analise como JSON e processe o evento.
`file`	Arquivo de mídia enviado opcionalmente quando o WaGo encaminha mídia baixada.

Comportamento mínimo do receptor:

Analise os dados do formulário.
Analise o jsonData.
Armazene o evento bruto.
Armazene índices-chave como token, type, ID da mensagem, JID do chat, JID do remetente e timestamp.
Salve os arquivos enviados antes de responder.
Responda com 2xx rapidamente.
Coloque ações lentas em fila após a resposta.

Veja Eventos de webhook para exemplos de eventos.

Passo 6: Manipule mídias

Para mídias de saída, escolha um dos dois padrões:

Padrão	Use quando
Base64 data URL	Os arquivos são pequenos e já estão disponíveis em sua aplicação.
Direct URL	Os arquivos são grandes ou já estão armazenados em um armazenamento de objetos/CDN.

Para mídias de entrada, use o encaminhamento de arquivos via webhook, se habilitado. Se você não receber o arquivo, use os metadados de mídia do evento da mensagem e chame o endpoint de download correspondente.

Passo 7: Fluxo de solução de problemas em produção

Quando algo falhar, verifique nesta ordem:

GET /server/ok para confirmar se o binário está acessível.
GET /session/status para confirmar o token, a conexão e o login.
GET /webhook para confirmar a URL do webhook e as assinaturas.
Logs do servidor para o status da requisição e erro do WhatsApp.
Logs do seu receptor de webhook para erros de entrega e análise.
O explorador de API local em http://localhost:1337/api para um teste direto de endpoint.

Erros comuns em produção

Problema	Solução
Frontend usa `admintoken`	Mova as chamadas administrativas para seu backend.
Página de QR code nunca atualiza	Faça polling em `/session/status` e atualize `/session/qr` apenas quando necessário.
Mensagens são enviadas, mas a aplicação não atualiza	Inscreva-se em `ReadReceipt` e armazene os eventos de webhook.
Mídia falha através de proxy	Aumente os limites de tamanho do corpo da requisição e de timeout.
Webhooks chegam várias vezes	Desduplique pelo ID da mensagem ou chave do evento.
Chamadas do navegador falham em produção	Use HTTPS tanto para sua aplicação quanto para a API do WaGo.
Chamadas funcionam localmente, mas não para alguns usuários	A rede pode exigir TURN, que está marcado como “em breve”.

​Arquitetura

​Passo 1: Armazene o token do WaGo em sua aplicação

​Passo 2: Configure os webhooks

​Passo 3: Exiba o status da leitura (scan)

​Passo 4: Envie uma mensagem

​Passo 5: Receba mensagens

​Passo 6: Manipule mídias

​Passo 7: Fluxo de solução de problemas em produção

​Erros comuns em produção