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}}

format: connect (recomendado) ou legacy (formato alternativo para integrações existentes). Cada URL específica substitui a geral para seu evento. URL deve ser HTTPS pública na porta 443. O salvamento renova o segredo de assinatura e cancela entregas pendentes da configuração anterior. 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.

Formato alternativo de recebimento inclui type: "ReceivedCallback", messageId, phone, chatId, chatLid, fromMe, fromApi, isGroup, senderName e objetos por tipo: text.message, audio.audioUrl, image.imageUrl, video.videoUrl, document.documentUrl, sticker.stickerUrl. Contém campos adicionais eventId e downloadAvailable. Em falha de download, URL pode ser null e error informa indisponibilidade. Não trate esse evento como arquivo válido.

Status no formato alternativo: type: "MessageStatusCallback", ids: ["ID_WHATSAPP"], status: "SENT" | "RECEIVED" | "READ" | "PLAYED" | "FAILED" | "PENDING". 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. A identidade de envio é mantida durante a retenção local.

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