Documentação da API

A API REST do Giro Connect permite integrar WhatsApp ao seu sistema. Gerencie sessões, envie mensagens, configure webhooks e automatize fluxos de comunicação.

Autenticação

A API utiliza tokens JWT para usuários do dashboard e API Keys (prefixo sk_) para acesso programático.

API Key

Envie a chave no header Authorization: Bearer sk_.... Crie chaves no dashboard com escopos como messages:send, contacts:read.

# Autenticação com API Key
curl -X GET "https://api.giro.aara.com.br/api/v1/usage" \
  -H "Authorization: Bearer sk_abc123_sua_chave_aqui"

JWT (Dashboard)

Faça login para obter um token JWT. Envie no header Authorization: Bearer <token>.

{
  "email": "user@example.com",
  "password": "sua_senha"
}

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer"
}

Mensagens

Envie e consulte mensagens WhatsApp. Suporta texto, imagens, documentos, áudio, vídeo e localização.

{
  "session_id": "uuid-da-sessao",
  "to": "5511999999999",
  "type": "text",
  "text": "Olá! Mensagem enviada pela API.",
  "idempotency_key": "idemp-unico-para-evitar-duplicatas"
}

{
  "id": "uuid-da-mensagem",
  "status": "queued",
  "direction": "outbound",
  "created_at": "2026-06-25T10:00:00Z"
}

{
  "items": [
    {
      "id": "uuid",
      "body_text": "Olá!",
      "direction": "outbound",
      "status": "sent",
      "created_at": "2026-06-25T10:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 50
}

Sessões WhatsApp

Gerencie conexões WhatsApp via QR Code. Cada organização pode ter múltiplas sessões (limite por plano).

{
  "display_name": "Meu WhatsApp",
  "provider": "waha"
}

{
  "id": "uuid",
  "status": "created",
  "provider_session_id": "giro_abc123_Meu WhatsApp",
  "created_at": "2026-06-25T10:00:00Z"
}

{
  "qr_code": "data:image/png;base64,...",
  "expires_at": "2026-06-25T10:05:00Z"
}

{
  "phone_e164": "5511999999999",
  "reason": "Spam"
}

Contatos

Gerencie contatos com opt-in/opt-out. Contatos que optaram por sair não recebem mensagens.

{
  "phone_e164": "5511999999999",
  "name": "Maria Silva",
  "email": "maria@example.com",
  "tags": ["cliente", "vip"]
}

Automações

Crie automações baseadas em templates prontos para resposta automática, lembretes, captura de leads e mais.

{
  "template_id": "uuid-do-template",
  "name": "Resposta de Cardápio",
  "config": {
    "keywords": ["cardapio", "menu"],
    "reply_text": "Confira nosso cardápio: https://exemplo.com/cardapio"
  }
}

Campanhas

Dispare mensagens em massa para contatos segmentados com agendamento e rastreamento por destinatário.

{
  "session_id": "uuid-da-sessao",
  "name": "Promoção de Junho",
  "message_template": "Olá {{nome}}, temos uma oferta especial!",
  "audience_filter": { "tags": ["cliente"] },
  "scheduled_at": "2026-07-01T09:00:00Z"
}

Webhooks

Receba eventos em tempo real. Cada webhook é assinado com HMAC-SHA256 para verificação de integridade.

{
  "url": "https://meusistema.com/webhooks/giro",
  "environment": "test",
  "subscribed_events": [
    "message.received",
    "message.delivered",
    "session.connected"
  ]
}

Exemplo: Verificar webhook em Python

import hashlib, hmac

def verify_webhook(payload: bytes, signature: str, secret: str, timestamp: str) -> bool:
    signing_content = f"{timestamp}.{payload.decode()}"
    expected = hmac.new(
        secret.encode(),
        signing_content.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Rate Limits

Limites configurados por organização, chave de API e sessão para evitar abuso.

Quando o limite é excedido, a API retorna

SDKs

Bibliotecas para integrar o Giro Connect na sua stack.