Skip to main content

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

​
Validar o workspace

​
Configurar os arquivos de ambiente

Copie os arquivos de exemplo antes de iniciar o workspace:
Se você estiver trabalhando no comportamento do worker ou do runtime de webhooks, também popule:
apps/control-plane foi removido. Não crie um .env.local para ele.

​
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 para o contrato completo de configuração de runtime.

​
Iniciar o workspace

​
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