Skip to main content
Bem-vindo à referência da API do Switchbord. O Switchbord oferece uma API REST pública estável (v1) para gerenciamento de workspaces, sincronização de contatos e envio de mensagens, além de camadas de compatibilidade especializadas para integrações legadas.

​
Primeiros passos

A API está acessível em https://api.switchbord.ai/v1 (ou no seu domínio auto-hospedado). Todas as requisições devem ser autenticadas usando uma API Key enviada no header X-API-Key. Você pode gerenciar as API Keys na seção Settings > Integrations > API Keys do painel do Switchbord.

​
Superfície principal v1

A API v1 é focada em operações de alto nível para workflows automatizados:
  • GET /v1/contacts - Lista e filtra contatos do workspace.
  • POST /v1/messages - Envia mensagens (texto, mídia ou template) para um contato.
  • GET /v1/templates - Busca templates aprovados do WhatsApp.
  • POST /v1/broadcasts - Dispara um broadcast pré-definido para um segmento.

​
Ingestão de Webhook do Provider

O Switchbord lida com toda a complexidade dos desafios de webhook da Meta e da verificação de assinatura:
  • POST /webhooks/whatsapp - Ingestão principal para eventos da WhatsApp Business Platform.
Essas rotas tratam a verificação de challenge, a validação de assinatura e o enfileiramento de jobs seguro contra replay.

​
Endpoints de compatibilidade

Para facilitar a migração de sistemas legados, mantemos aliases de compatibilidade para o Charles e outras plataformas comuns:
  • PUT /api/v1beta/contact/
  • POST /webhooks/v0/rest-trigger/...
Consulte o guia Superfície de Compatibilidade para ver os mapeamentos exatos.

​
API interna e de extensão

Para operações forenses e administrativas, existe uma superfície de API interna (com o prefixo /internal). Esses endpoints são usados pela interface do Switchbord e estão sujeitos a alterações.
  • GET /internal/audit-logs
  • GET /internal/webhook-events

​
Postura e confiabilidade

  • Totalmente tipada: Todos os endpoints são modelados com TypeScript e validados na borda (edge).
  • Fila em primeiro lugar (Queue-First): Os payloads de webhook são persistidos no banco de dados e normalizados antes de serem processados por workers em segundo plano.
  • Limitação de taxa (Rate Limiting): Limites padrão se aplicam aos endpoints v1. Contate o suporte para necessidades de alto volume.