Skip to main content
Esta página é para quem vai ligar um sistema ao Notifique para criar conexões, ler o QR e enviar mensagens pela API. Se você só usa o painel, dá para parear e enviar por lá também; a API é para automação e produtos próprios.

​
Antes de começar

Você vai precisar de:
  • Uma chave de API do workspace certo. Cada chave pertence a um workspace — a API resolve isso sozinha. Não envie o cabeçalho x-workspace-id na v1 (se vier preenchido, a API responde 400).
  • Permissões na chave para o que você for fazer — por exemplo criar/listar instâncias e enviar mensagens (na documentação técnica: whatsapp:instances:create, whatsapp:instances:list, whatsapp:send; leitura e desconectar são opcionais conforme o caso).
  • A URL base da API (nos exemplos: https://api.notifique.dev — troque pela sua, se for outra).
Substitua sk_live_xxxxx pela sua chave real.

​
O caminho em três passos

  1. Criar uma conexão (instância) e mostrar o QR para alguém escanear no WhatsApp do número.
  2. Quando ficar ativa, aquele número está pronto para enviar.
  3. Enviar mensagem informando qual conexão usar e para qual telefone.
Abaixo está o mesmo fluxo com exemplos de pedido e resposta.

​
1. Criar instância

Cria a conexão e devolve o QR para pareamento (enquanto estiver “pendente”). Pedido 
POST /v1/whatsapp/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Minha Instância"
}
Resposta (200) — exemplo 
{
  "success": true,
  "data": {
    "instance": {
      "id": "cmmc8wjkt000dqf01d2nlb0gv",
      "name": "Minha Instância",
      "status": "PENDING",
      "phoneNumber": null,
      "createdAt": "2026-03-04T16:22:50.909Z"
    },
    "connection": {
      "pairingCode": null,
      "code": "2@KbXFfHsvo+byvkP6k4VoBIE5gZFwYHT9y6dNt/c6Sfg6M+...",
      "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAVwAAAFcCAYAAACEFgYs...",
      "count": 1
    }
  }
}
  • instance: dados da conexão (id, nome, status; o telefone aparece depois do pareamento).
  • connection.base64: imagem do QR (pode exibir em uma tag <img> no seu painel interno).
  • O QR expira rápido; use o passo 2 ou webhooks para renovar.

​
2. Obter um QR novo

Quando o QR “vence”, você busca outro sem recriar a instância. Pedido 
GET /v1/whatsapp/instances/:instanceId/qr
Authorization: Bearer sk_live_xxxxx
Resposta (200) — ainda esperando o scan 
{
  "success": true,
  "data": {
    "status": "PENDING",
    "base64": "data:image/png;base64,iVBORw0KGgo..."
  }
}
Resposta (200) — já conectado 
{
  "success": true,
  "data": {
    "status": "ACTIVE",
    "base64": null
  }
}
Dá para consultar de tempos em tempos (polling) ou deixar o webhook avisar quando sair QR novo ou quando conectar.

​
3. Receber avisos (webhook) — opcional

Na configuração de webhooks do workspace, inclua eventos como:
  • novo QR gerado;
  • número conectado;
  • instância desconectada.
Quem recebe o POST deve conferir a assinatura com o segredo do webhook (HMAC no corpo bruto, como descrito na documentação de eventos). Assim você evita falsos avisos.

​
4. Enviar mensagem de texto

Com a instância ativa, envie para uma lista de números (formato internacional, como no exemplo). Pedido 
POST /v1/whatsapp/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "instanceId": "clxx...",
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Olá! Mensagem de teste."
  }
}
Resposta (202) — exemplo 
{
  "messageIds": ["clxxmsg..."],
  "status": "QUEUED",
  "scheduledAt": null
}
Há opções extras (prioridade, retentativas, webhook só daquele envio, metadados). O detalhe está no OpenAPI do canal, rota POST /v1/whatsapp/messages.

​
Continuar

Nota: consultar a instância por GET no id não devolve o QR; use GET /v1/whatsapp/instances/:id/qr quando precisar da imagem.