API — Connect 0.2

Autenticação

API nativa: Authorization: Bearer TOKEN. A chave administrativa permite gestão global; o token de instância ou a chave de integração concede acesso somente à instância correspondente. Criar projetos, alterar configurações, conectar/desconectar, gerir chaves e excluir exige administração. Chaves de integração são mostradas somente na criação e podem ser revogadas individualmente. A renovação do token de instância invalida o token anterior.

API nativa

Texto e idempotência

curl -X POST "$BASE_URL/api/instances/$INSTANCE_ID/messages" \
  -H "Authorization: Bearer $INSTANCE_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-teste-001' \
  -d '{"phone":"5511999999999","type":"text","text":"Mensagem de teste"}'

Resposta HTTP 202: { "id": "ID_DA_FILA", "whatsappId": "ID_WHATSAPP", "status": "queued", "reused": false }.

id identifica o item local; whatsappId identifica a mensagem do protocolo, reservado antes do envio. Retornar um ID não significa que o destinatário recebeu. A mesma chave de idempotência e conteúdo reutilizam a operação; conteúdo diferente retorna 409. Use uma chave estável por operação, não uma chave nova a cada tentativa de rede.

Destino: telefone com DDI, 123456789-group, JID 123456789@g.us ou LID explícito 123456789@lid. Não adivinhe telefone a partir de LID.

Envio de mídia nativa

{"phone":"5511999999999","type":"audio","base64":"BASE64_SEM_PREFIXO","mimetype":"audio/wav","fileName":"teste.wav","ptt":true}

Tipos: text, image, audio, video, document, sticker. Para mídia, base64 e mimetype obrigatórios; até 32 MiB. caption opcional (não para áudio), fileName recomendado para documento. ptt:true no áudio converte para voz Ogg Opus. A conversão pode retornar 422 sem enfileirar o envio se o arquivo não for decodificável.

Webhooks

PUT substitui todos os destinos. Campos omitidos ficam vazios. Exemplo:

{"format":"connect","url":"https://app.exemplo.com/webhook?token=SEGREDO_DO_CONSUMIDOR","received":"","delivery":"","status":"","connected":"","disconnected":"","presence":"","settings":{"notifyFromMe":true,"ignoreGroups":true}}

Os eventos usam exclusivamente o formato connect. O campo format é opcional e, quando informado, aceita somente connect. Cada URL específica substitui a geral para seu evento. URL deve ser HTTPS pública na porta 443. O salvamento preserva o segredo de assinatura. Apenas entregas pendentes para URLs removidas são canceladas. GET /api/instances/:id/webhook/secret consulta a chave; POST no mesmo caminho gera outra explicitamente e cancela as entregas pendentes. Atualize os consumidores após essa renovação. Não copie o webhook de produção para um teste: ele pode acionar a IA real.

Formato nativo: { "id", "instanceId", "type", "createdAt", "data" }. Tipos centrais: message.received, message.sent, message.status, message.failed, message.uncertain, connection.update, chat.presence.

Recebimento: type: "message.received". O objeto data contém messageId, from, phone, chatLid, participant, fromMe, fromApi, name, type e text. Mídias usam data.media.url, mimetype, fileName, seconds, voiceNote e downloadAvailable. Se o download falhar, a URL pode ser nula e error informa a indisponibilidade. Não trate esse evento como arquivo válido.

Status: type: "message.status", com data.messageId, data.whatsappId e data.status (pending, sent, delivered, read, played ou failed). Correlacione pelo ID, nunca pelo texto. Resposta humana do próprio número tem fromMe:true, fromApi:false; eco identificado de envio desta API tem fromApi:true.

Verificação de assinatura

Headers: X-Connect-Event-Id, X-Connect-Timestamp, X-Connect-Signature: sha256=HEX. Calcule HMAC-SHA256 com o segredo retornado no salvamento sobre timestamp + "." + corpo_raw. Compare em tempo constante, rejeite timestamps muito antigos e deduplique por ID de evento. O corpo deve ser verificado antes de parsear/reformatar JSON.

Entregas: até oito tentativas com espera exponencial; qualquer 2xx confirma. Erros e timeouts ficam visíveis no painel. Reentrega reutiliza o ID e corpo original. O consumidor deve ser idempotente. Falha de webhook não reenvia a mensagem ao WhatsApp.

Configurações booleanas

ignoreDelivery, ignoreReceived, ignoreStatus, ignorePresence, ignoreConnected, ignoreDisconnected, notifyFromMe, ignoreGroups, ignorePrivate, ignoreText, ignoreImage, ignoreVideo, ignoreAudio, ignoreDocument, autoRejectCalls, autoReadMessages, autoReadStatus, protectAnnouncementGroups, disableOfflineQueue.

Padrão: false em todas. Filtros afetam entrega de webhook, não o registro recebido no painel. Mensagens próprias só são notificadas quando notifyFromMe está ligado.

Erros e limites

400 entrada inválida, 401 sem autenticação, 403 acesso de outra instância/origem inválida, 404 recurso ausente, 409 conflito/fila desconectada, 413 arquivo grande, 422 opção ou conversão não suportada, 429 limite, 501 endpoint não implementado, 504 timeout de download. Limite HTTP: 300 chamadas/minuto por IP de conexão; considere o proxy na implantação. Fila: mil envios por instância, expiração em 24h. Não reenvie automaticamente uma operação uncertain.

Links /media/...?... são assinados e funcionam sem Bearer até expirar. Quem possui o link pode baixar o arquivo: trate-o como dado confidencial. Armazenamento cifrado, validade de 30 dias, sem arquivar mídias de visualização única.

Variáveis na Vercel

No painel, abra a instância e escolha Conexão → Integrar com Vercel. O guia mostra os nomes e permite copiar os valores sem renovar o token.

Para apps novos, o código do servidor deve ler CONNECT_API_URL (origem HTTPS sem /api), CONNECT_INSTANCE_ID, CONNECT_API_TOKEN e, se receber eventos, CONNECT_WEBHOOK_SECRET. O token pode ser uma chave exclusiva criada em Integrações para a API nativa. A chave do webhook é retornada ao configurar o destino; ela não é o token de envio.

Para a integração existente da Lola no Labrego IA, selecione o perfil específico: LABREGO_CONNECT_URL, LABREGO_CONNECT_INSTANCE_ID, LABREGO_CONNECT_TOKEN e LABREGO_CONNECT_WEBHOOK_SECRET. As quatro são obrigatórias nesse consumidor. Ele usa o token da instância e o formato alternativo de webhook. Outros apps podem usar nomes diferentes; confirme o contrato do código antes de mudar variáveis.

Na Vercel: Settings → Environment Variables, selecione Production, use Secret para credenciais e faça um novo deploy. Não use NEXT_PUBLIC_ ou VITE_ para segredos. Cadastrar variáveis sozinho não implementa a integração. Não renove webhooks que já funcionam sem atualizar o segredo em todos os consumidores.

Referência: https://vercel.com/docs/environment-variables/managing-environment-variables

Pareamento por telefone

POST /api/instances/:id/pairing-code exige acesso de gestor e recebe { "phone": "5511999999999" } (DDI + DDD + número, sem sinais). Retorna um código temporário para digitar em WhatsApp → Aparelhos conectados → Conectar aparelho → Conectar com número de telefone. Não desconecta instâncias já conectadas (409); limita nova solicitação a uma por minuto (429). A resposta usa Cache-Control: no-store; códigos não são enviados a webhooks nem registrados em eventos. O usuário precisa concluir o pareamento no próprio celular.