Introdução

O que é a Hosthy API e como ela funciona.

A Hosthy API é a interface REST oficial da plataforma para integrações com WhatsApp Business. Permite que desenvolvedores gerenciem contatos, conversas, enviem mensagens e recebam eventos em tempo real.

Construída sobre a Meta WhatsApp Cloud API — todas as mensagens passam pela infraestrutura oficial da Meta com garantias de entrega, criptografia e compliance.

Autenticação

Todas as requisições exigem uma API Key válida.

Formato do token

Cada chave é um token de 56 caracteres hexadecimais gerado aleatoriamente — sem prefixo.

a3f8c2e1d94b7065f2a1c8e3b47d92f0e6c5a1b8d3e7f094c2a6b1e5d8f3a970

Como enviar

Use o header Authorization: Bearer ou X-API-Key:

Authorization: Bearer SEU_TOKEN

# ou via header alternativo
X-API-Key: SEU_TOKEN

Verificar autenticação

curl https://api.hosthy.com.br/public-api/v1/me \
  -H "Authorization: Bearer SEU_TOKEN"

# Resposta 200 OK
{
  "keyId": "550e8400-...",
  "tenantId": "550e8400-...",
  "scopes": ["contacts.read", "messages.send"],
  "tenant": {
    "name": "Minha Empresa",
    "subdomain": "minhaempresa",
    "plan": "business"
  }
}

Gerar uma API Key

1. Acesse o painel Hosthy
2. Vá em Configurações → API Keys
3. Clique em Nova API Key
4. Escolha um nome descritivo e os scopes necessários
5. Copie a chave gerada — ela é exibida uma única vez

Scopes

Cada API Key tem scopes que definem as operações permitidas.

Use o princípio do menor privilégio — conceda apenas os scopes necessários para cada integração.

Formato & Erros

Todas as respostas são JSON com Content-Type: application/json.

Resposta de sucesso

// HTTP 200 OK
{
  "contacts": [...],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

Resposta de erro

// HTTP 401 Unauthorized
{
  "error": "API key required. Use Authorization: Bearer <key>"
}

Erro de validação (400)

// HTTP 400 Bad Request
{
  "error": "Validation error",
  "details": {
    "fieldErrors": {
      "phone": ["String must contain at least 7 characters"]
    }
  }
}

Paginação

Endpoints de listagem suportam paginação via query params.

curl "https://api.hosthy.com.br/public-api/v1/contacts?page=2&limit=25&search=Joao" \
  -H "Authorization: Bearer SEU_TOKEN"

Rate Limit

Limites de requisições por minuto por IP/chave.

Limite excedido retorna 429 Too Many Requests. Implemente retry com backoff exponencial.

// HTTP 429 Too Many Requests
{ "error": "Rate limit exceeded. Retry after 60 seconds." }

Contatos

Gerencie a base de contatos da sua conta Hosthy.

curl "https://api.hosthy.com.br/public-api/v1/contacts?limit=10" \
  -H "Authorization: Bearer SEU_TOKEN"

# Resposta 200 OK
{
  "contacts": [
    {
      "id": "CONTACT_ID",
      "name": "João Silva",
      "phone": "5551992371100",
      "email": "[email protected]",
      "notes": null,
      "contactTags": []
    }
  ],
  "pagination": { "total": 1, "page": 1, "limit": 10, "pages": 1 }
}

curl -X POST https://api.hosthy.com.br/public-api/v1/contacts \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "phone": "5541991392989",
    "email": "[email protected]"
  }'

Normalização de telefone

Nono dígito BR: Números com 13 dígitos são convertidos para 12 conforme padrão Meta.

Conversas

Threads de comunicação com contatos via WhatsApp.

curl "https://api.hosthy.com.br/public-api/v1/conversations?status=open&limit=10" \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X POST \
  "https://api.hosthy.com.br/public-api/v1/conversations/CONV_ID/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Olá! Como posso ajudar?"}'

Status de Mensagens

Ciclo de vida das mensagens enviadas.

Os status delivered e read chegam via webhook da Meta. Configure webhooks de saída para recebê-los em tempo real.

Janela de 24 horas

Regra fundamental da Meta WhatsApp Business Platform.

Verificar estado (painel autenticado)

// GET /conversations/{id}/meta-state
{
  "within24hWindow": true,
  "windowExpiresAt": "2024-01-16T08:00:00Z",
  "remainingSeconds": 14400,
  "canSendFreeform": true,
  "requiresTemplate": false
}

Templates WhatsApp

Mensagens pré-aprovadas pela Meta para uso fora da janela 24h.

Templates pertencem ao WABA do cliente — criados e aprovados no Meta Business Manager, não pela Hosthy.

Categorias

Status de aprovação

Custos Meta

Separação de cobranças entre Hosthy e Meta.

Webhooks de Saída

Receba eventos da Hosthy em tempo real no seu sistema.

Eventos disponíveis

Criar endpoint (painel autenticado)

// POST /webhooks
{
  "name": "Meu CRM",
  "url": "https://meu-sistema.com/webhook",
  "events": ["message.received", "message.sent"]
}

Verificar assinatura HMAC

Cada entrega inclui o header X-Hosthy-Signature: sha256=<hmac>. Sempre verifique antes de processar:

const crypto = require('crypto')

function verifySignature(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}

// No handler do webhook:
const sig = req.headers['x-hosthy-signature']
if (!verifySignature(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
  return res.status(401).end()
}

Retries e idempotência

Retries automáticos em caso de timeout ou status não-2xx (até 5 tentativas com backoff exponencial). Seu endpoint deve responder com 2xx e processar eventos de forma idempotente.

Segurança

Boas práticas para integrações seguras com a API.

• Mantenha a API Key no backend — nunca no frontend, app mobile ou repositório público
• Use variáveis de ambiente para armazenar a chave no servidor
• HTTPS obrigatório — todas as requisições exigem HTTPS
• Verifique assinatura HMAC em todos os webhooks recebidos
• Menor privilégio — conceda apenas os scopes necessários por chave
• Rotacione periodicamente e imediatamente se suspeitar de comprometimento
• Uma chave por integração — facilita rastreamento e revogação granular
• Não logue API Keys — filtre os headers de Authorization nos seus logs

Erros Comuns

Referência rápida para os códigos de erro HTTP da API.

Boas Práticas

Recomendações para integrações robustas e eficientes.

Geral

• Use webhooks em vez de polling para receber eventos em tempo real
• Implemente retry com backoff exponencial para falhas temporárias (5xx, 429)
• Processe webhooks de forma idempotente — o mesmo evento pode chegar mais de uma vez
• Valide o telefone no formato canonical WhatsApp antes de criar contatos
• Monitore message.failed para detectar problemas de entrega proativamente
• Mantenha templates APPROVED prontos para contatos fora da janela 24h

Rate limit

• Não implemente polling mais frequente que 1×/minuto
• Em caso de 429, aguarde o tempo indicado antes de tentar novamente
• Distribua requisições no tempo — evite burst de chamadas simultâneas

Janela 24h

• Verifique within24hWindow via /meta-state antes de enviar mensagens
• Tenha templates utility aprovados para ativar conversas sem janela aberta
• Monitore a expiração via campo windowExpiresAt

Changelog

Histórico de versões e mudanças da API.

v1.4 — Pricing Awareness & Janela 24h

• /conversations/{id}/meta-state — estado da janela 24h em tempo real
• /conversations/{id}/messages/preview — prévia antes do envio
• Classificação de mensagens: service, utility, marketing, authentication
• Bloqueio automático de texto livre fora da janela 24h

v1.3 — Meta Templates Cache

• Cache local de templates WABA via /meta/templates
• Sincronização via /meta/templates/sync
• /tenant/meta/status e /meta/pricing-awareness

v1.2 — Webhooks de Saída

• Webhooks com assinatura HMAC-SHA256 (/webhooks)
• Eventos: message.*, conversation.*, tag.*, automation.executed
• Retries automáticos com backoff e logs de entrega

v1.5 — Tokens sem prefixo

• Tokens gerados como 56 hex chars puros — sem prefixo proprietário
• Suporte a Authorization: Bearer e X-API-Key

v1.1 — API Keys Públicas

• Sistema de API Keys com scopes granulares
• Rate limiting por endpoint e por chave

v1.0 — Lançamento

• API pública: contatos, conversas, mensagens, tags
• Integração com Meta Cloud API
• Normalização automática de telefone BR/WhatsApp