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

# Guia rápido

> Comece a usar o Switchbord — configuração hospedada ou local para contribuidores.

## Opção A — Hospedado (app.switchbord.ai)

Se você é um operador entrando em uma equipe existente ou iniciando um novo workspace na plataforma hospedada:

1. Cadastre-se em [app.switchbord.ai](https://app.switchbord.ai).
2. Crie um workspace (ou aceite um convite de um admin de um workspace existente).
3. Vá em **Settings → Provider** e conecte sua conta Meta Business e o número de WhatsApp.
4. Siga o guia [Conectar o WhatsApp](/pt-BR/platform/connect-whatsapp) para o passo a passo completo de configuração de credenciais.

Se você foi convidado para um workspace e chega em `/pending-access`, seu convite ainda está sendo processado. Contate o admin do seu workspace.

***

## Opção B — Configuração local para contribuidores

### Instalar

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

### Validar o workspace

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

### Configurar os arquivos de ambiente

Copie os arquivos de exemplo antes de iniciar o workspace:

```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 você estiver trabalhando no comportamento do worker ou do runtime de webhooks, também popule:

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

<Note>
  `apps/control-plane` foi removido. Não crie um `.env.local` para ele.
</Note>

#### Variáveis mínimas do Supabase

* `NEXT_PUBLIC_SUPABASE_URL`
* `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`
* `SUPABASE_SECRET_KEY` — para caminhos administrativos do lado do servidor
* `WHATSAPP_PLATFORM_DATA_MODE=supabase` — apenas para superfícies com uma implementação real apoiada no Supabase
* `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS` — recomendado para qualquer ambiente compartilhado ou hospedado, para definir o primeiro operador privilegiado
* `WORKSPACE_ALLOW_FIRST_CLAIM=true` — apenas para a reivindicação intencional e única de owner pelo primeiro usuário durante o bootstrap local

O repositório ainda aceita `NEXT_PUBLIC_SUPABASE_ANON_KEY` e `SUPABASE_SERVICE_ROLE_KEY` como aliases legados, mas novas configurações devem usar as formas de publishable key e secret key.

#### Variáveis mínimas da Meta (para um loop real de webhook mais envio)

* `WHATSAPP_META_ACCESS_TOKEN` — para o worker
* `WEBHOOK_SIGNATURE_SECRET` — para `apps/api`
* `META_WEBHOOK_VERIFY_TOKEN` — para verificação explícita do challenge de webhook
* `SUPABASE_DB_URL` — se estiver usando o Supabase Vault para segredos de provedor gerenciados pelo workspace

Se um usuário autenticado ainda não estiver provisionado em um workspace, o app do operador o direciona para `/pending-access` até que um convite seja aceito ou as regras de bootstrap concedam a membership.

Se o primeiro operador local ficar preso em `/pending-access`, não exclua o usuário de autenticação. Corrija o bootstrap definindo `WORKSPACE_BOOTSTRAP_ADMIN_EMAILS`, habilitando temporariamente `WORKSPACE_ALLOW_FIRST_CLAIM=true`, ou inserindo manualmente a linha ausente em `workspace_members`.

Veja [Ambiente](/pt-BR/environment) para o contrato completo de configuração de runtime.

### Iniciar o workspace

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

### Portas locais

* app: `3000`
* web: `3001`
* api: `3002`
* docs: `3004`
* storybook: `6006`
* worker: processo em segundo plano, sem porta HTTP

### Rotas de alto valor

* caixa de entrada do operador: `http://localhost:3000/inbox`
* diagnósticos de runtime: `http://localhost:3000/runtime`
* prontidão da API: `http://localhost:3002/ready`
* especificação OpenAPI: `http://localhost:3002/spec`
* ingress de webhook da Meta: `http://localhost:3002/webhooks/meta`

### Premissas de trabalho

* feature flags têm valor padrão `on`
* o contrato de ambiente do Supabase deve ser satisfeito antes que qualquer superfície use o Supabase diretamente
* a migração somente para frente (forward-only) é a postura ativa
* a migração histórica de mensagens está intencionalmente fora do escopo deste primeiro recorte

## Leia a seguir

* [Conectar o WhatsApp](/pt-BR/platform/connect-whatsapp)
* [Configuração de webhook](/pt-BR/platform/webhook-setup)
* [Como contribuir](/pt-BR/contributing)
* [Arquitetura para contribuidores](/pt-BR/contributing/architecture)
* [Ambiente](/pt-BR/environment)