Skip to main content
Benvenuto nel riferimento API di Switchbord. Switchbord fornisce un’API REST pubblica stabile (v1) per la gestione dei workspace, la sincronizzazione dei contatti e l’invio di messaggi, insieme a livelli di compatibilità specializzati per le integrazioni legacy.

​
Per iniziare

L’API è accessibile all’indirizzo https://api.switchbord.ai/v1 (o il tuo dominio self-hosted). Tutte le richieste devono essere autenticate utilizzando una API Key passata nell’header X-API-Key. Puoi gestire le API Key nella sezione Settings > Integrations > API Keys della dashboard di Switchbord.

​
Superficie core v1

L’API v1 si concentra su operazioni di alto livello per i workflow automatizzati:
  • GET /v1/contacts - Elenca e filtra i contatti del workspace.
  • POST /v1/messages - Invia messaggi (testo, media o template) a un contatto.
  • GET /v1/templates - Recupera i template WhatsApp approvati.
  • POST /v1/broadcasts - Attiva una broadcast predefinita verso un segmento.

​
Ingresso Webhook del Provider

Switchbord gestisce la complessità delle challenge webhook di Meta e della verifica delle firme:
  • POST /webhooks/whatsapp - Ingresso primario per gli eventi della WhatsApp Business Platform.
Queste route gestiscono la verifica della challenge, la validazione della firma e l’accodamento dei job sicuro rispetto ai replay.

​
Endpoint di compatibilità

Per facilitare la migrazione dai sistemi legacy, manteniamo alias di compatibilità per Charles e altre piattaforme comuni:
  • PUT /api/v1beta/contact/
  • POST /webhooks/v0/rest-trigger/...
Consulta la guida Superficie di compatibilità per le mappature esatte.

​
Estensione e API interna

Per operazioni forensi e amministrative, esiste una superficie API interna (con prefisso /internal). Questi endpoint sono utilizzati dalla UI di Switchbord e sono soggetti a modifiche.
  • GET /internal/audit-logs
  • GET /internal/webhook-events

​
Postura e affidabilità

  • Completamente tipizzata: Tutti gli endpoint sono modellati con TypeScript e validati all’edge.
  • Queue-First: I payload dei webhook vengono persistiti nel database e normalizzati prima di essere elaborati dai worker in background.
  • Rate Limiting: Si applicano limiti predefiniti agli endpoint v1. Contatta il supporto per esigenze ad alto volume.