> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Riferimento API

> API REST pubblica v1, livelli di compatibilità e ingresso dei webhook.

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à](/it/api-reference/compatibility) 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.