Guias & Recursos

Tudo que você precisa para integrar a Hasos no seu sistema.

Início rápido

Do zero à primeira chamada em quatro passos.

1
Crie sua chave de API
Gere uma chave em Configurações → Chaves de API e envie-a no header x-api-key. Use sempre a partir do seu servidor — nunca no navegador.
bash
curl https://api.hasos.com.br/v1/instances \ -H "x-api-key: hs_live_sua_chave"
Criar chave

Conecte um número de WhatsApp

Crie um dispositivo e vincule o WhatsApp via QR Code ou código de pareamento. Cada dispositivo é um número.

bash

# cria o dispositivo
curl -X POST https://api.hasos.com.br/v1/instances \
  -H "x-api-key: hs_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"phone":"5511999999999"}'

# obtém o código de pareamento para esse dispositivo
curl https://api.hasos.com.br/v1/instances/INSTANCE_ID/pairing-code \
  -H "x-api-key: hs_live_sua_chave"

Adicionar dispositivo

Incorpore o discador no seu app

Emita um token do dispositivo e cole o iframe do discador no seu produto. O token autentica aquele número no navegador — faça chamadas sem backend de voz (receber chamadas está em beta).

bash

curl -X POST https://api.hasos.com.br/v1/instances/INSTANCE_ID/tokens \
  -H "x-api-key: hs_live_sua_chave"

html

<iframe
  src="https://phone.hasos.com.br?token=SEU_TOKEN"
  allow="microphone"
  style="width:420px;height:640px;border:0;border-radius:8px"
></iframe>

Abrir um dispositivo

Receba eventos via webhook

Aponte uma URL para receber eventos de chamada. Cada entrega é assinada — valide o header x-webhook-signature com o seu secret (veja abaixo).

bash

curl -X POST https://api.hasos.com.br/v1/instances/INSTANCE_ID/webhook \
  -H "x-api-key: hs_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seu-app.com/webhooks/voz"}'

Configurar webhook

Links rápidos

Chaves de API

Crie e revogue chaves para autenticar suas requisições à API.

Gerenciar chaves

Dispositivos

Conecte números de WhatsApp e gere tokens para o discador.

Ver dispositivos

Webhooks

Receba eventos de chamadas assinados (HMAC) em tempo real.

Configurar

Ligações & métricas

Acompanhe histórico, taxa de atendimento e volume de chamadas.

Abrir relatórios

Endpoints principais

Base: https://api.hasos.com.br · autenticação via header x-api-key.

POST/v1/instancesCria um dispositivo (número)
GET/v1/instancesLista os dispositivos da conta
GET/v1/instances/:id/pairing-codeCódigo de pareamento do WhatsApp
GET/v1/instances/:id/qrQR Code para vincular o WhatsApp
POST/v1/instances/:id/tokensEmite um token do discador
POST/v1/instances/:id/webhookDefine a URL do webhook (retorna o secret)
GET/v1/instances/:id/webhook/deliveriesEntregas recentes do webhook
GET/v1/callsHistórico de chamadas da conta
GET/v1/calls/:id/recordingLink (assinado) da gravação da chamada
GET/v1/analyticsMétricas agregadas (taxa de atendimento, volume…)
GET/v1/api-keysLista chaves (mascaradas)

Validação de webhooks

Cada entrega chega com o header x-webhook-signature = sha256=<HMAC>. Calcule o HMAC SHA-256 do corpo bruto com o secret do dispositivo e compare.

Verificar a assinatura (Node.js)

import crypto from "node:crypto";

// rawBody = corpo BRUTO da requisição (antes de JSON.parse)
function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Formato do payload

json

// Envelope comum a todos os eventos:
// { "event": "CALL" | "RECORD" | "DEVICE", "instanceId", "phone", "timestamp", "data" }
// "phone" = número de WhatsApp da instância (null enquanto não pareado).

// Evento CALL — enviado em ringing, answered e ended (entrada e saída):
{
  "event": "CALL",
  "instanceId": "a1b2c3d4",
  "phone": "5511988887777",
  "timestamp": "2026-07-01T13:14:41.077Z",
  "data": {
    "type": "answered",          // ringing | answered | ended
    "callId": "00ED0D44…",
    "direction": "OUTGOING",     // OUTGOING | INCOMING
    "peerPhone": "5511999999999",
    "durationSec": 23,            // preenchido no "ended"
    "endReason": "ended"          // preenchido no "ended"
  }
}

// Evento RECORD — enviado quando a gravação fica pronta, com link de download:
{
  "event": "RECORD",
  "instanceId": "a1b2c3d4",
  "phone": "5511988887777",
  "timestamp": "2026-07-01T13:15:10.000Z",
  "data": {
    "callId": "00ED0D44…",
    "direction": "OUTGOING",
    "peerPhone": "5511999999999",
    "url": "https://s3.hasos.com.br/recordings/…?X-Amz-Signature=…", // válido 7 dias
    "objectKey": "recordings/00ED0D44….mp3",
    "contentType": "audio/mpeg",
    "durationSec": 23,
    "sizeBytes": 123456
  }
}