API de instâncias WhatsApp
Integre seu ERP, CRM ou sistema interno com instâncias WhatsApp via REST: criar sessões, parear QR, enviar mensagens, listar conversas e receber eventos por webhook. Autenticação por API Key — sem misturar com o token Sanctum do console.
https://api.instvia.com/api/v1Credenciais: gere a API Key no console (o valor
sk_live_... aparece só na criação). Nesta documentação usamos valores de exemplo.
Autenticação
Envie estes headers nas requisições da API ERP (exceto o healthcheck público).
| Header | Obrigatório | Descrição |
|---|---|---|
Authorization |
Sim | Bearer com a API Key da empresa: `Bearer sk_live_...`. |
Accept |
Não | Recomendado: `application/json`. |
Content-Type |
Não | Obrigatório em POST/PATCH com body: `application/json`. |
Idempotency-Key |
Não | Opcional no envio de mensagens. Evita duplicar o mesmo envio em retries. |
X-Request-ID |
Não | ID de correlação opcional; útil para suporte e logs. |
Exemplo: Authorization: Bearer sk_live_…
Observações
Esta documentação cobre a API para ERP (API Key). Tokens Sanctum do console/admin não funcionam nestes endpoints — e a API Key não autentica rotas administrativas. Envelope padrão: sucesso `{ "success": true, "data": ... }` e erro `{ "success": false, "error": { "code", "message" } }`. Crie a chave no console (app.instvia.com); o valor `sk_live_...` aparece só na criação. URLs de webhook devem ser HTTPS públicas (localhost e IPs privados são bloqueados).
Endpoints
Healthcheck
Público. Verifica se a API, MySQL e Redis estão respondendo. Sem autenticação. Inclui a ve...
GETListar instâncias
Lista todas as instâncias WhatsApp da empresa autenticada pela API Key.
POSTCriar instância
Cria uma nova sessão WhatsApp. Status inicial: `CREATED`. Em seguida chame Connect e Get Q...
GETObter instância
Detalhe de uma instância pelo UUID.
PATCHAtualizar instância
Atualiza campos da instância (ex.: nome).
DELETEExcluir instância
Remove a instância da empresa.
POSTConectar
Abre a sessão no Engine (Baileys). Pode levar alguns segundos até o WhatsApp emitir o QR....
GETObter QR Code
Retorna a string de pareamento e a imagem PNG em data URI. Use `?format=png` para receber...
GETStatus da instância
Retorna o estado atual da instância (mesmo shape do Get instance).
POSTReiniciar sessão
Reinicia a sessão no Engine sem excluir a instância.
POSTDesconectar
Desvincula o aparelho (logout no WhatsApp), apaga as credenciais locais e exige novo QR no...
POSTEnviar texto
Enfileira uma mensagem de texto. Responde `202` com status `QUEUED`. O Horizon processa o...
GETListar mensagens
Últimas 200 mensagens da instância (mais recentes primeiro). Filtro opcional por `peer`.
GETObter mensagem
Detalhe de uma mensagem pelo UUID.
GETListar conversas
Inbox da instância: um item por número (`peer`), com a última mensagem e contagem. Inclui...
GETMensagens da conversa
Histórico de um número (até 200 mensagens, ordem cronológica). Respostas inbound também en...
GETObter webhook
Retorna a configuração de webhook da instância (sem o secret).
POSTCriar / substituir webhook
Cria ou substitui o webhook da instância. Cada POST gera um `secret` novo (rotaciona o ant...
PATCHAtualizar webhook
Atualiza URL, lista de eventos ou status (`ACTIVE` / `DISABLED`). Não regenera o secret.
DELETERemover webhook
Remove a configuração de webhook da instância.
POSTWebhook
Receba notificações no seu sistema quando houver atualizações.