> ## 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.

# Guida rapida

> Inizia a lavorare con Switchbord — configurazione hosted o locale per contributori.

## Opzione A — Hosted (app.switchbord.ai)

Se sei un operatore che si unisce a un team esistente o avvia una nuova area di lavoro sulla piattaforma hosted:

1. Registrati su [app.switchbord.ai](https://app.switchbord.ai).
2. Crea un'area di lavoro (oppure accetta l'invito di un admin di un'area di lavoro esistente).
3. Vai su **Impostazioni → Provider** e collega il tuo account Meta Business e il numero di telefono WhatsApp.
4. Segui la guida [Connetti WhatsApp](/it/platform/connect-whatsapp) per il percorso completo di configurazione delle credenziali.

Se sei stato invitato a un'area di lavoro e finisci su `/pending-access`, il tuo invito è ancora in elaborazione. Contatta l'admin della tua area di lavoro.

***

## Opzione B — Configurazione locale per contributori

### Installazione

```bash theme={null}
pnpm install
```

### Convalida dell'area di lavoro

```bash theme={null}
pnpm lint
pnpm docs:lint
pnpm typecheck
pnpm test
```

### Configura i file di ambiente

Copia i file di esempio prima di avviare l'area di lavoro:

```bash theme={null}
cp apps/app/.env.example apps/app/.env.local
cp apps/api/.env.example apps/api/.env.local
cp apps/web/.env.example apps/web/.env.local
```

Se stai lavorando sul comportamento del worker o del runtime dei webhook, esegui anche:

```bash theme={null}
cp apps/worker/.env.example apps/worker/.env.local
```

<Note>
  `apps/control-plane` è stato rimosso. Non creare un file `.env.local` per esso.
</Note>

#### Variabili minime di Supabase

* `NEXT_PUBLIC_SUPABASE_URL`
* `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`
* `SUPABASE_SECRET_KEY` — per i percorsi admin lato server
* `WHATSAPP_PLATFORM_DATA_MODE=supabase` — solo per le superfici con un'implementazione reale basata su Supabase
* `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS` — consigliata per qualsiasi ambiente condiviso o hosted, per impostare il primo operatore privilegiato
* `WORKSPACE_ALLOW_FIRST_CLAIM=true` — solo per la richiesta intenzionale e una tantum del ruolo owner da parte del primo utente durante il bootstrap locale

Il repository accetta ancora `NEXT_PUBLIC_SUPABASE_ANON_KEY` e `SUPABASE_SERVICE_ROLE_KEY` come alias legacy, ma la nuova configurazione dovrebbe usare le forme publishable key e secret key.

#### Variabili minime di Meta (per un ciclo reale di webhook più invio)

* `WHATSAPP_META_ACCESS_TOKEN` — per il worker
* `WEBHOOK_SIGNATURE_SECRET` — per `apps/api`
* `META_WEBHOOK_VERIFY_TOKEN` — per la verifica esplicita della challenge del webhook
* `SUPABASE_DB_URL` — se usi Supabase Vault per i segreti dei provider gestiti dall'area di lavoro

Se un utente autenticato non è ancora stato inserito in un'area di lavoro, l'app operatore lo instrada su `/pending-access` finché un invito non viene accettato o le regole di bootstrap non concedono l'appartenenza.

Se il primo operatore locale rimane bloccato su `/pending-access`, non eliminare l'utente auth. Risolvi il bootstrap impostando `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS`, abilitando temporaneamente `WORKSPACE_ALLOW_FIRST_CLAIM=true`, oppure inserendo manualmente la riga mancante in `workspace_members`.

Consulta [Ambiente](/it/environment) per il contratto completo di configurazione del runtime.

### Avvia l'area di lavoro

```bash theme={null}
pnpm dev
```

### Porte locali

* app: `3000`
* web: `3001`
* api: `3002`
* docs: `3004`
* storybook: `6006`
* worker: processo in background, nessuna porta HTTP

### Percorsi più utili

* posta in arrivo dell'operatore: `http://localhost:3000/inbox`
* diagnostica del runtime: `http://localhost:3000/runtime`
* readiness dell'API: `http://localhost:3002/ready`
* specifica OpenAPI: `http://localhost:3002/spec`
* ingress webhook Meta: `http://localhost:3002/webhooks/meta`

### Ipotesi di lavoro

* i feature flag sono attivi (`on`) di default
* il contratto env di Supabase deve essere soddisfatto prima che qualsiasi superficie usi Supabase direttamente
* la migrazione forward-only è la postura attiva
* la migrazione storica dei messaggi è intenzionalmente fuori dall'ambito per la prima versione

## Leggi anche

* [Connetti WhatsApp](/it/platform/connect-whatsapp)
* [Configurazione dei webhook](/it/platform/webhook-setup)
* [Contribuire](/it/contributing)
* [Architettura per i contributori](/it/contributing/architecture)
* [Ambiente](/it/environment)