Integração de qualquer app

App novo

• Crie um projeto e uma instância no painel. Pareie o WhatsApp.
• Em Integrações, crie uma chave exclusiva para o novo sistema. Guarde-a no backend/gerenciador de segredos, nunca no JavaScript público do navegador.
• Configure uma rota HTTPS no novo app para receber eventos e verificar a assinatura. Se usar formato nativo, associe os eventos por instanceId e data.messageId/data.whatsappId.
• Salve o webhook nesta instância; guarde o segredo de assinatura retornado.
• Envie por /api/instances/:id/messages com Bearer e Idempotency-Key; acompanhe o estado por webhook ou GET.
• Faça testes ponta a ponta antes de habilitar automações. A chave de um sistema não acessa outra instância.

Uma instância possui um destino por tipo de evento. Se múltiplos sistemas precisarem receber o mesmo evento, use uma rota distribuidora própria que faça fan-out com deduplicação, ou instâncias separadas. Criar várias chaves não cria vários destinos de webhook.

JavaScript (backend)

const response = await fetch(`${process.env.CONNECT_URL}/api/instances/${process.env.CONNECT_INSTANCE}/messages`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CONNECT_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-123-confirmacao-v1',
  },
  body: JSON.stringify({ phone: '5511999999999', type: 'text', text: 'Teste autorizado' }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);
// Persistir result.id e result.whatsappId; não tratar queued como entregue.

Python (backend, biblioteca padrão)

import os, json, urllib.request
url = f"{os.environ['CONNECT_URL']}/api/instances/{os.environ['CONNECT_INSTANCE']}/messages"
request = urllib.request.Request(url, method='POST', headers={
    'Authorization': 'Bearer ' + os.environ['CONNECT_TOKEN'],
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-123-confirmacao-v1',
}, data=json.dumps({'phone': '5511999999999', 'type': 'text', 'text': 'Teste autorizado'}).encode())
with urllib.request.urlopen(request, timeout=30) as response:
    result = json.load(response)
# Persistir IDs e acompanhar confirmação; em timeout consultar antes de reenviar.

Webhook nativo em Express

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
const app = express();
// Esta rota deve vir ANTES de express.json(), preservando o corpo original.
app.post('/connect/webhook', express.raw({ type: 'application/json', limit: '1mb' }), async (req, res) => {
  const timestamp = req.get('X-Connect-Timestamp') || '';
  const received = req.get('X-Connect-Signature') || '';
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now()/1000 - Number(timestamp)) > 300) return res.sendStatus(401);
  const expected = 'sha256=' + createHmac('sha256', process.env.CONNECT_WEBHOOK_SECRET)
    .update(timestamp + '.').update(req.body).digest('hex');
  if (received.length !== expected.length || !timingSafeEqual(Buffer.from(received), Buffer.from(expected))) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  // Persistir em fila própria com chave única event.id ANTES de responder 2xx.
  // Duplicata já persistida: responder 200 sem repetir o processamento.
  // Falha ao persistir: responder 5xx para permitir nova tentativa.
  await persistEventIdempotently(event); // Implementação depende do banco do seu app.
  res.sendStatus(200);
});

Integrações existentes

Para migrar um sistema para o Connect, identifique seus contratos de envio e recebimento, configure a URL base e uma chave própria, e adapte o consumidor para os eventos documentados na API. Faça a troca em homologação antes da produção.

• Teste uma instância e um consumidor por vez.
• Confirme igualdade entre os IDs de envio e confirmação.
• Verifique assinatura, deduplicação, mídias, mensagens próprias e eventos de leitura.
• Confira grupos e LIDs se seu sistema os utiliza.
• Publique o Connect em HTTPS para integrações fora deste computador.
• Guarde a configuração anterior do sistema para recuperação, caso algum fluxo falhe.

Nenhum nome de aplicativo, empresa ou projeto é exigido pela API. Crie novos projetos, instâncias e credenciais pelo painel conforme precisar.