Rooms

O Rooms transforma uma videochamada em registro de negócio. Você cria uma sessão pela API, manda um link curto para o cliente, e ao final tem três coisas guardadas e presas à sua organização: quem entrou e por quanto tempo, o que foi dito — transcrito em português, separado por quem falou — e, se você pediu, o vídeo gravado em MP4.

Na prática isso resolve o atendimento que hoje acontece numa plataforma de reunião genérica e some. O analista faz a chamada, a evidência fica num arquivo pessoal dele, e três meses depois ninguém consegue provar o que foi combinado. Com o Rooms, a mesma chamada devolve GET /sessions/:id/transcript e GET /sessions/:id/recording, e quem lê precisa da permissão ROOMS_READ na organização dona da sessão.

flowchart LR
  A["POST /sessions<br/>(sua esteira)"] --> B["link com joinCode<br/>(o cliente clica)"]
  B --> C["chamada de vídeo<br/>(navegador, sem conta)"]
  C --> D["participantes<br/>quem entrou e por quanto tempo"]
  C --> E["transcrição em pt-BR<br/>separada por quem falou"]
  C --> F["MP4 no seu S3<br/>por URL assinada"]
  D --> G["tudo preso à organização<br/>e lido só com ROOMS_READ"]
  E --> G
  F --> G

Está em produção desde julho de 2026, no domínio rooms-api.bb.catalisa.app, e foi validado ponta a ponta em produção: vídeo, gravação em MP4 e transcrição em português real, com 17 trechos transcritos corretamente no teste de aceitação. O histórico completo do rollout, com armadilhas de custo e de operação, está no runbook de produção.

O cenário. Uma operação precisa falar com o cliente por vídeo — validação de identidade, entrevista de crédito, consulta, atendimento de sinistro — e precisa que essa conversa deixe rastro. Não é reunião interna: é atendimento com consequência contratual.

O que trava hoje.

• A plataforma de reunião genérica não conhece o seu cliente. Ela exige conta, ou instalação, ou as duas coisas. Cada fricção na entrada é um atendimento que não acontece.
• A evidência fica fora do sistema. A gravação vai para a nuvem pessoal de quem organizou a chamada. Não há permissão por organização, não há retenção definida, não há como responder a uma auditoria sem pedir favor.
• Transcrever depois é um segundo projeto. Contratar um serviço de transcrição, mover o arquivo, tratar formato de áudio, ligar ao registro certo. Cada etapa é uma integração nova.
• Construir sobre WebRTC parece barato e não é. O SDK entrega a sala. Sessão, código de convidado, papéis, contabilização de minutos, ciclo de vida da gravação e isolamento entre clientes continuam sendo código seu — e é aí que mora o esforço.
• O consentimento vira post-it. Gravar voz e imagem de uma pessoa exige aceite. Sem isso no fluxo, o aceite acaba sendo uma frase que alguém fala no começo da chamada e ninguém registra.

O desenho abaixo é o caminho que a evidência percorre hoje, numa operação que usa plataforma de reunião genérica — e os quatro pontos em que ela se perde.

flowchart TD
  A["atendimento marcado"] --> B["cliente instala o app<br/>ou cria conta"]
  B -->|desistência| X1["atendimento que não acontece"]
  B --> C["chamada acontece"]
  C --> D["gravação vai para a nuvem pessoal<br/>de quem organizou"]
  D --> X2["sem permissão por organização<br/>sem retenção definida"]
  C --> E["transcrever é outro projeto:<br/>serviço novo, mover arquivo, ligar ao registro"]
  E --> X3["integração adicional para cada etapa"]
  C --> F["aceite de gravação foi uma frase falada"]
  F --> X4["nada registrado — problema de LGPD<br/>que só aparece quando alguém pergunta"]

O custo de não resolver. O custo visível é o time de engenharia que passa um trimestre construindo a camada de sessão em cima de um SDK. O custo invisível é maior: gravação de voz e imagem é dado pessoal, e voz é biometria comportamental. Uma operação que grava sem aceite registrado e sem controle de acesso não tem um problema de produto — tem um problema de LGPD que só aparece quando alguém pergunta.

Entrada sem atrito, do lado do cliente. O convidado usa POST /join/:joinCode — rota pública, sem token, protegida por limite de 20 tentativas por minuto por IP. Ele recebe o token da sala e entra pelo navegador.

Evidência com dono. Toda sessão pertence a uma organização. A transcrição e a gravação passam pela mesma checagem de tenant antes de qualquer leitura, e uma sessão de outro cliente responde 404, não 403 — não dá nem para descobrir que ela existe.

Os dois ganhos acima são o mesmo caminho visto dos dois lados — o convidado entra sem conta, e mesmo assim nada entra sem aceite nem sai sem tenant:

flowchart TD
  A["convidado abre o link"] --> B["POST /join/:joinCode<br/>rota pública, sem token"]
  B --> C{"20 req/min<br/>por IP?"}
  C -->|excedeu| E1["429 com Retry-After"]
  C -->|dentro| D{"lgpdAccepted<br/>exatamente true?"}
  D -->|não| E2["400 — reprovado na validação<br/>antes de emitir qualquer token"]
  D -->|sim| F{"código válido?"}
  F -->|sessão encerrada| E3["410 SESSION_ENDED"]
  F -->|expirado| E4["410 JOIN_CODE_EXPIRED"]
  F -->|válido| G["grava lgpdAcceptedAt no participante"]
  G --> H["emite token de sala + serverUrl"]
  H --> I["leitura depois:<br/>transcript e recording só com ROOMS_READ<br/>na organização dona — senão 404"]

Transcrição como dado, não como legenda. Cada trecho finalizado vira uma linha em RoomUtterance com texto, idioma, papel (host ou guest), identidade do participante e marcação de tempo em milissegundos. Dá para buscar, resumir e usar em regra de decisão.

Contabilização automática de minutos. O participantMinutes da sessão é acumulado a partir dos eventos de entrada e saída do LiveKit, inclusive fechando quem ficou pendurado quando a sala terminou.

Panorama. O mercado de vídeo em tempo real se estabilizou em torno de um modelo: SDK mais nuvem, cobrança por minuto de participante, com gravação e transcrição como adicionais medidos. LiveKit, Daily, 100ms e Agora vendem essencialmente o mesmo formato, com diferenças de preço, presença geográfica e maturidade de SDK. A parte open source também amadureceu — o servidor LiveKit é Apache 2.0 (github.com/livekit/livekit), o que torna a fuga do fornecedor de nuvem uma opção real.

O que nenhum deles resolve é a distância entre "tem uma sala" e "tem um atendimento registrado". Essa distância são semanas de trabalho: modelo de sessão, código de convidado com expiração, papéis, aceite de gravação, contabilização de minutos, ciclo de vida do egress, isolamento entre clientes. O Rooms é exatamente essa camada, e por isso ele usa o LiveKit em vez de concorrer com ele.

Nossos diferenciais

1. A sala já sabe de quem ela é. RoomSession.organizationId é preenchido a partir do token e toda leitura passa por getSession, que devolve 404 quando a sessão é de outro tenant. Um SDK de vídeo não tem como oferecer isso: ele não sabe o que é uma organização no seu produto.
2. O convidado entra sem conta e o aceite fica gravado. joinByCodeSchema exige lgpdAccepted: true — literalmente z.literal(true), não um booleano qualquer. Sem aceite, a requisição é reprovada na validação, antes de qualquer token de sala ser emitido. É difícil de copiar porque exige que o consentimento esteja no caminho crítico, não num aviso na tela.
3. A transcrição nasce estruturada e sai como evento. Cada trecho finalizado é uma linha com participante, papel, idioma e marcação de tempo, e publica rooms.v1.utterance.finalized no mesmo barramento dos outros building blocks. A chamada deixa de ser mídia e vira dado que a esteira consome.
4. A gravação não fica órfã. Um webhook perdido deixaria o registro preso em active para sempre, com o MP4 no S3 e inalcançável pela API. Na leitura, o Rooms consulta o provedor e reconcilia o estado terminal. Isso veio de um problema real: havia seis registros nesse estado em staging, com zero egress em andamento no LiveKit (runbook §9).

Quando escolher o concorrente

A árvore abaixo é a resposta curta; o parágrafo em seguida é a mesma resposta com o porquê de cada ramo.

flowchart TD
  A["o que você precisa?"] --> B{"centenas de participantes,<br/>transmissão ou SDK nativo do fornecedor?"}
  B -->|sim| C["Daily, 100ms ou Agora<br/>o Rooms nasce com teto de 4 e não tem cliente próprio"]
  B -->|não| D{"vídeo é o núcleo<br/>do seu negócio?"}
  D -->|sim| E["LiveKit Cloud direto<br/>controle total, servidor Apache 2.0"]
  D -->|não| F{"quer agente de IA que<br/>conversa em tempo real?"}
  F -->|sim| G["LiveKit Agents<br/>o nosso agente hoje só transcreve"]
  F -->|não| H["Catalisa Rooms<br/>o vídeo é uma etapa do processo<br/>e o que importa é o registro que sobra"]

Se você precisa de uma sala com centenas de participantes, de transmissão para audiência, de layouts sofisticados de palco ou de SDK nativo para iOS e Android mantido pelo fornecedor, compre Daily, 100ms ou Agora — o Rooms hoje nasce com teto de 4 participantes por sala e não tem cliente próprio, você monta a interface com o SDK do LiveKit. Se o seu produto é vídeo e o vídeo é o núcleo do negócio, vá direto ao LiveKit Cloud: você terá controle total, o servidor é Apache 2.0 e não haverá camada intermediária. E se o que você quer é um agente de IA que conversa com o participante em tempo real, o framework LiveKit Agents faz isso e o nosso agente hoje só transcreve (§15). O Rooms ganha quando o vídeo é uma etapa de um processo que já vive na plataforma — e o que importa é o registro que sobra depois.

Unidade de cobrança. Precificação em definição. O Rooms já acumula participantMinutes por sessão, o que é a base natural de medição, mas ainda não há emissão de uso para o Billing (§15).

O que dispara custo. Três drivers, e eles não pesam igual:

O que a franquia mostrou em staging

Vale repetir o que foi medido em staging entre 20 e 28 de julho de 2026 (runbook §9). Os três drivers consumiram franquia em escalas completamente diferentes:

Mais da metade da franquia de egress foi consumida por testes casuais, enquanto vídeo e transcrição mal arranharam as suas. O gargalo é a gravação, com folga.

Comparação de custo

Cenário: 500 atendimentos por mês, 12 minutos cada, 2 participantes, com transcrição ligada e gravação em metade deles. São 12.000 minutos de participante, 6.000 minutos de sala transcrita e 3.000 minutos de gravação. Preços consultados em 2026-08-16.

Estimativa para orientar conversa, não proposta comercial. As tabelas dos fornecedores mudam e há descontos por volume em todos eles — consulte na data da sua análise. O custo de engenharia da coluna "você constrói" é estimativa interna.

ROI

ROI. A conta não fecha no minuto: comprar minuto direto do fornecedor de infraestrutura é sempre mais barato que comprar de qualquer intermediário. A conta fecha na camada.

Sessão com dono, código de convidado com expiração, aceite registrado, papéis, contabilização de minutos, ciclo de vida do egress com reconciliação e isolamento entre clientes são o que o Rooms entrega pronto — e é a parte que, construída do zero sobre um SDK, é medida em trimestre, não em sprint.

flowchart LR
  A["minuto de mídia"] -->|"mais barato direto no fornecedor"| B["o ROI não está aqui"]
  C["camada de sessão:<br/>dono, convidado, aceite, papéis,<br/>minutos, egress reconciliado, isolamento"] -->|"do zero sobre um SDK:<br/>trimestre, não sprint"| D["o ROI está aqui"]
  E["armadilhas já pagas<br/>ex.: emptyTimeout de 600s"] --> D

O Rooms são dois processos, e isso não é detalhe de implantação — é a decisão arquitetural central.

As duas peças e o que cada uma fala

flowchart TD
  H["navegador do host<br/>POST /sessions<br/>POST /sessions/:id/tokens/host"]
  G["navegador do convidado<br/>POST /join/:joinCode (público)"]

  subgraph S["serviço rooms — imagem monolito, Bun, basePath('/rooms')"]
    R1["/api/v1/sessions · sessionRouter<br/>ROOMS_READ · ROOMS_WRITE"]
    R2["/api/v1/join · joinRouter<br/>público, 20/min por IP"]
    R3["/livekit/webhooks · livekitWebhook<br/>assinatura do LiveKit"]
    R4["RoomSessionService · RoomsMediaService · RoomsWebhookService"]
  end

  H --> R1
  G --> R2

  PG[("PostgreSQL<br/>schema rooms")]
  LK["LiveKit Cloud<br/>sala · token · egress · agent"]
  RD[("Redis stream<br/>rooms.v1.*")]

  S -->|Prisma| PG
  S -->|"SDK server"| LK
  S -->|EventPublisher| RD

  subgraph W["processo rooms-agent-worker — imagem PRÓPRIA, Node 22"]
    W1["@livekit/agents + @livekit/rtc-node<br/>entra na sala, assina só ÁUDIO,<br/>empurra frames 16kHz mono"]
    W2["Deepgram STT (nova-3)"]
    W3["legenda ao vivo no stream lk.transcription"]
    W4["RoomUtterance no Postgres<br/>+ rooms.v1.utterance.finalized"]
    W1 --> W2 --> W3
    W2 --> W4
  end

  LK -->|"dispatch do agente"| W1
  W1 -.->|"mídia (WebRTC)"| LK
  W4 --> PG
  W4 --> RD

  LK -->|"Egress escreve MP4 direto"| S3[("seu bucket S3")]
  S3 -->|"GET /sessions/:id/recording<br/>devolve URL assinada"| S

Caminho de uma sessão, do POST à gravação

O diagrama acima mostra as peças; este mostra a ordem em que elas se falam numa chamada real, com transcrição e gravação ligadas.

sequenceDiagram
  autonumber
  participant App as "sua aplicação"
  participant Rooms as "serviço rooms"
  participant DB as "PostgreSQL"
  participant LK as "LiveKit"
  participant Guest as "convidado"
  participant Scribe as "rooms-agent-worker"
  participant DG as "Deepgram"
  participant S3 as "seu bucket S3"

  App->>Rooms: "POST /sessions"
  Rooms->>DB: "cria a linha (status scheduled)"
  Rooms->>LK: "createRoom org_<org>_<sessionId>"
  Rooms-->>App: "201 com joinCode e roomName"

  Guest->>Rooms: "POST /join/:joinCode (lgpdAccepted true)"
  Rooms->>DB: "grava participante e lgpdAcceptedAt"
  Rooms->>DB: "scheduled to live no primeiro join"
  Rooms-->>Guest: "token de sala e serverUrl"
  Guest->>LK: "conecta pelo SDK cliente"

  LK->>Rooms: "webhook room_started"
  Rooms->>LK: "dispatchAgent (se transcriptionEnabled)"
  Rooms->>LK: "startRecording egress (se recordingEnabled)"
  Rooms->>DB: "RoomRecording status active"

  LK->>Scribe: "job despachado ao agente"
  Scribe->>LK: "entra na sala, AUDIO_ONLY"
  loop "a cada trecho de fala"
    Scribe->>DG: "frames 16kHz mono"
    DG-->>Scribe: "texto do trecho"
    Scribe->>LK: "legenda ao vivo em lk.transcription"
    Scribe->>DB: "RoomUtterance"
    Scribe-->>App: "rooms.v1.utterance.finalized"
  end

  App->>Rooms: "POST /sessions/:id/end"
  Rooms->>LK: "deleteRoom"
  Rooms->>DB: "status ended e endedAt"
  LK->>Rooms: "webhook room_finished"
  Rooms->>DB: "fecha pendurados e soma participantMinutes"
  Rooms-->>App: "rooms.v1.session.ended"

  LK->>S3: "grava o MP4"
  LK->>Rooms: "webhook egress_ended"
  Rooms->>DB: "RoomRecording completed com bucketKey"
  Rooms-->>App: "rooms.v1.recording.ready"
  App->>Rooms: "GET /sessions/:id/recording"
  Rooms-->>App: "URL assinada"

Decisões não óbvias

• O worker de agente roda numa imagem separada, em Node 22. Todos os outros building blocks compartilham a imagem monolito e se distinguem pelo command. O rooms-agent-worker não pode: o @livekit/rtc-node tem bindings nativos que não rodam sob Bun. O preço é uma imagem a mais para construir e implantar; a alternativa era não ter transcrição.
• O agente entra na sala como participante e assina só áudio. AutoSubscribe.AUDIO_ONLY. Ele não precisa de vídeo para transcrever, e vídeo custaria banda e franquia. O efeito colateral é conhecido: enquanto o agente estiver na sala, ela não fecha sozinha — quem encerra é o POST /end (runbook §3).
• O nome do agente é resolvido em tempo de execução, por ambiente. Um projeto LiveKit compartilhado coloca todos os workers registrados com o mesmo nome no mesmo pool, e o LiveKit despacha a sala para qualquer um. O worker do ambiente errado grava RoomUtterance com um sessionId que não existe no banco dele, viola a chave estrangeira e a transcrição não sai — nos dois ambientes. Por isso ROOMS_SCRIBE_AGENT_NAME existe, e por isso o serviço rooms e o rooms-agent-worker precisam ler o mesmo valor.
• A legenda ao vivo é atribuída ao falante, não ao agente. O senderIdentity do stream de texto é a identidade de quem falou. Se fosse o agente, toda legenda apareceria rotulada como o bot.
• O webhook do LiveKit valida contra o corpo cru. A rota lê c.req.text() antes de qualquer parsing, porque o WebhookReceiver recalcula a assinatura sobre os bytes exatos recebidos. Reserializar o JSON quebraria a verificação.
• Nenhum handler de webhook lança exceção. O LiveKit reentrega em resposta diferente de 2xx, e um handler que estoura viraria tempestade de reentrega. As falhas são registradas em log e a rota responde 200. Pelo mesmo motivo, falha no despacho do agente ou no início da gravação é tratada como não fatal: transcrição e gravação são aditivas, e nenhuma delas vale derrubar a chamada de vídeo.
• A gravação é reconciliada na leitura, não no encerramento. Só o webhook egress_ended tira um registro de active, e webhook é entrega de melhor esforço. Reconciliar no POST /end correria com o egress ainda em EGRESS_ENDING; reconciliar na leitura acontece muito depois, sem corrida. Falha na consulta ao provedor é engolida de propósito — o pior caso volta a ser o 404 de antes.
• O limite de entrada por código é por processo, em memória. createInMemoryRateLimiter com 20 tentativas por minuto por IP. Isso pressupõe uma réplica do serviço, que é o cenário atual. Com N réplicas, o teto efetivo vira 20×N. Antes de escalar, isso precisa migrar para o limitador compartilhado em Redis (§15).
• O nome da sala carrega a organização. org_<organizationId>_<sessionId>. Assim um evento de webhook que traz só o nome da sala já é rastreável até o tenant, sem consulta extra.

Monolito vs. standalone

Em monolito, o roomsApp é montado junto com os demais e os serviços vêm do container TypeDI. Em standalone — o modo de produção — o rooms sobe como serviço próprio e o rooms-agent-worker sobe como segundo serviço, com imagem própria. O worker não fala HTTP com o rooms: ele escreve direto no Postgres e publica no Redis. Se você subir só o rooms, tudo funciona menos a transcrição.

Glossário

Modelo de dados

Schema rooms no PostgreSQL.

Como as cinco tabelas se ligam

Tudo pendura na sessão. Participantes, trechos e gravações caem por cascata quando a RoomSession é apagada — e o RoomProviderConfig fica de fora justamente porque nenhum código o lê hoje.

erDiagram
  RoomSession ||--o{ RoomParticipant : "quem entrou"
  RoomSession ||--o{ RoomUtterance : "o que foi dito"
  RoomSession ||--o{ RoomRecording : "o que foi gravado"
  RoomProviderConfig }o..o| RoomSession : "previsto, não usado hoje"

  RoomSession {
    string organizationId
    enum status "scheduled live ended"
    string roomName UK
    string joinCode UK
    datetime joinCodeExpiresAt
    boolean recordingEnabled
    boolean transcriptionEnabled
    int participantMinutes
  }
  RoomParticipant {
    string identity UK "único com sessionId"
    string role "host ou guest"
    datetime lgpdAcceptedAt
    datetime joinedAt
    datetime leftAt
  }
  RoomUtterance {
    string participantIdentity
    string text
    int startMs
    int endMs
    boolean isFinal
  }
  RoomRecording {
    string egressId UK
    string status "active completed failed"
    string bucketKey
    int durationMs
  }

Ciclo de vida da sessão

O enum RoomSessionStatus tem exatamente três valores — scheduled, live e ended — e a sessão nasce em scheduled.

stateDiagram-v2
  [*] --> scheduled : "POST /sessions"
  scheduled --> live : "primeiro join OU webhook room_started"
  live --> ended : "POST /end OU webhook room_finished"
  scheduled --> ended : "POST /end OU webhook room_finished"

  scheduled --> scheduled : "join com código expirado → 410 JOIN_CODE_EXPIRED"
  ended --> ended : "join em sessão encerrada → 410 SESSION_ENDED"

Em ended, o deleteRoom já foi chamado no LiveKit e os participantes pendurados são fechados com o mesmo endedAt, somando os minutos.

Ciclo de vida da gravação

A gravação tem máquina própria, com três estados na coluna status do RoomRecording: active, completed e failed.

stateDiagram-v2
  [*] --> active : "webhook room_started + recordingEnabled → startRecording (egress)"
  active --> completed : "webhook egress_ended OU reconciliação na leitura"
  active --> failed : "webhook egress_ended com status de falha"
  completed --> [*] : "GET /sessions/:id/recording → URL assinada"

Prefixo: /rooms. Em staging, a base é https://rooms-api.bb.stg.catalisa.app; em produção, https://rooms-api.bb.catalisa.app.

Sessões — /rooms/api/v1/sessions

Todas exigem authMiddleware → requirePermission(...) → requireOrganization.

Entrada de convidado — /rooms/api/v1/join

Webhook do provedor — /rooms/livekit/webhooks

Saúde

POST /rooms/api/v1/sessions

Cria a sessão no banco, cria a sala no provedor e devolve o registro completo. Se a criação da sala falhar, a linha do banco é removida — não fica sessão sem sala.

Request

{
  "title": "Entrevista de crédito — proposta 88213",
  "recordingEnabled": true,
  "transcriptionEnabled": true,
  "language": "pt-BR",
  "joinCodeTtlHours": 4,
  "metadata": { "propostaId": "88213" }
}

{
  "title": "Entrevista de crédito — proposta 88213",
  "recordingEnabled": true,
  "transcriptionEnabled": true,
  "language": "pt-BR",
  "joinCodeTtlHours": 4,
  "metadata": { "propostaId": "88213" }
}

Resposta 201 — o registro RoomSession completo, incluindo joinCode, joinCodeExpiresAt, roomName e status: "scheduled".

Erros

POST /rooms/api/v1/join/:joinCode

Rota pública. É por onde o convidado entra.

Request

{
  "displayName": "Maria Souza",
  "lgpdAccepted": true
}

{
  "displayName": "Maria Souza",
  "lgpdAccepted": true
}

Resposta 200

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "serverUrl": "wss://<projeto>.livekit.cloud",
  "session": { "id": "clx...", "title": "Entrevista de crédito", "status": "live" }
}

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "serverUrl": "wss://<projeto>.livekit.cloud",
  "session": { "id": "clx...", "title": "Entrevista de crédito", "status": "live" }
}

Use token e serverUrl com o SDK cliente do LiveKit. O token vale 2 horas.

Erros

Os dois casos de 410 chegam com code: "CONFLICT" no corpo e statusCode: 410 — a distinção precisa vem de details.code. Trate por details.code, não pelo code de topo.

GET /rooms/api/v1/sessions/:id/transcript

Resposta 200

{
  "utterances": [
    {
      "id": "clx...",
      "sessionId": "clx...",
      "participantIdentity": "host",
      "role": "host",
      "text": "Boa tarde, vamos confirmar os dados da proposta.",
      "language": "pt-BR",
      "startMs": 1200,
      "endMs": 4800,
      "isFinal": true,
      "createdAt": "2026-08-16T14:02:11.000Z"
    }
  ]
}

{
  "utterances": [
    {
      "id": "clx...",
      "sessionId": "clx...",
      "participantIdentity": "host",
      "role": "host",
      "text": "Boa tarde, vamos confirmar os dados da proposta.",
      "language": "pt-BR",
      "startMs": 1200,
      "endMs": 4800,
      "isFinal": true,
      "createdAt": "2026-08-16T14:02:11.000Z"
    }
  ]
}

Lista vazia significa uma de três coisas: a sessão foi criada com transcriptionEnabled: false; o webhook do LiveKit não está cadastrado, então o agente nunca foi despachado; ou o worker não está de pé. Veja a receita de diagnóstico na §11.

GET /rooms/api/v1/sessions/:id/recording

Devolve URL assinada da última gravação concluída da sessão. Se não houver nenhuma concluída, o serviço consulta o provedor antes de desistir, para reconciliar gravação presa em active.

Resposta 200

{
  "url": "https://s3.bb.catalisa.app/files/rooms/recordings/...?X-Amz-Signature=...",
  "status": "completed",
  "durationMs": 726000,
  "sizeBytes": 184320512,
  "expiresIn": 3600
}

{
  "url": "https://s3.bb.catalisa.app/files/rooms/recordings/...?X-Amz-Signature=...",
  "status": "completed",
  "durationMs": 726000,
  "sizeBytes": 184320512,
  "expiresIn": 3600
}

Erros

Do zero à sala com convidado, em staging. Seis passos, um bloco por passo, com o que esperar de volta em cada um.

flowchart LR
  P1["1. autenticar<br/>no IAM"] --> P2["2. criar a sessão<br/>sem gravação"]
  P2 --> P3["3. token de host"]
  P3 --> P4["4. entrar como convidado<br/>pelo caminho público"]
  P4 --> P5["5. confirmar que o aceite<br/>é obrigatório"]
  P5 --> P6["6. encerrar — sempre"]

1. Autenticar no IAM

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

BASE=https://rooms-api.bb.stg.catalisa.app

TOKEN=$(curl -s -X POST https://iam.bb.stg.catalisa.app/iam/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catalisa.app",
    "password": "root123456",
    "organizationId": "b0000000-0000-0000-0000-000000000001"
  }' | jq -r .accessToken)

BASE=https://rooms-api.bb.stg.catalisa.app

Esperado: $TOKEN preenchido com o JWT. Se sair null, a organização ou a senha está errada — confira antes de seguir.

2. Criar a sessão — sem gravação no primeiro teste

SESSION=$(curl -s -X POST "$BASE/rooms/api/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Teste","transcriptionEnabled":true,"recordingEnabled":false,"joinCodeTtlHours":1}')

SESSION_ID=$(echo "$SESSION" | jq -r '.id')
JOIN_CODE=$(echo "$SESSION" | jq -r '.joinCode')
echo "sessão $SESSION_ID · código $JOIN_CODE"

SESSION=$(curl -s -X POST "$BASE/rooms/api/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"title":"Teste","transcriptionEnabled":true,"recordingEnabled":false,"joinCodeTtlHours":1}')

SESSION_ID=$(echo "$SESSION" | jq -r '.id')
JOIN_CODE=$(echo "$SESSION" | jq -r '.joinCode')
echo "sessão $SESSION_ID · código $JOIN_CODE"

Esperado: 201, com a sessão em scheduled e o código já emitido.

sessão clx7a2b9c0001abcd · código 7K4Q2M

sessão clx7a2b9c0001abcd · código 7K4Q2M

recordingEnabled: false de propósito. Gravação é a franquia mais apertada do provedor (§6) e o padrão do schema já é false — quem liga é quem chama.

3. Pegar o token de host

curl -s -X POST "$BASE/rooms/api/v1/sessions/$SESSION_ID/tokens/host" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"displayName":"Analista"}' | jq '{serverUrl, session}'

curl -s -X POST "$BASE/rooms/api/v1/sessions/$SESSION_ID/tokens/host" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"displayName":"Analista"}' | jq '{serverUrl, session}'

Esperado: serverUrl do projeto LiveKit e a sessão ainda em scheduled — o host não muda o status; quem vira live é o primeiro join.

{
  "serverUrl": "wss://<projeto>.livekit.cloud",
  "session": { "id": "clx...", "title": "Teste", "status": "scheduled" }
}

{
  "serverUrl": "wss://<projeto>.livekit.cloud",
  "session": { "id": "clx...", "title": "Teste", "status": "scheduled" }
}

4. Entrar como convidado, pelo caminho público

curl -s -X POST "$BASE/rooms/api/v1/join/$JOIN_CODE" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Maria Souza","lgpdAccepted":true}' | jq '{serverUrl, session}'

curl -s -X POST "$BASE/rooms/api/v1/join/$JOIN_CODE" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Maria Souza","lgpdAccepted":true}' | jq '{serverUrl, session}'

Esperado: 200, e agora a sessão aparece como live — este é o join que fez a transição.

{
  "serverUrl": "wss://<projeto>.livekit.cloud",
  "session": { "id": "clx...", "title": "Teste", "status": "live" }
}

{
  "serverUrl": "wss://<projeto>.livekit.cloud",
  "session": { "id": "clx...", "title": "Teste", "status": "live" }
}

O token e o serverUrl das respostas 3 e 4 vão para o SDK cliente do LiveKit. A partir daí é vídeo.

5. Confirmar que o aceite é obrigatório

curl -s -o /dev/null -w "%{http_code}\n" -X POST "$BASE/rooms/api/v1/join/$JOIN_CODE" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Maria Souza","lgpdAccepted":false}'

curl -s -o /dev/null -w "%{http_code}\n" -X POST "$BASE/rooms/api/v1/join/$JOIN_CODE" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Maria Souza","lgpdAccepted":false}'

Retorna 400. Não existe caminho em que alguém entre sem o aceite registrado.

6. Encerrar — sempre

curl -s -X POST "$BASE/rooms/api/v1/sessions/$SESSION_ID/end" \
  -H "Authorization: Bearer $TOKEN" | jq '{status, endedAt, participantMinutes}'

curl -s -X POST "$BASE/rooms/api/v1/sessions/$SESSION_ID/end" \
  -H "Authorization: Bearer $TOKEN" | jq '{status, endedAt, participantMinutes}'

Esperado: a sessão em ended, com a data de encerramento e os minutos já somados.

{ "status": "ended", "endedAt": "2026-08-16T14:22:03.000Z", "participantMinutes": 2 }

{ "status": "ended", "endedAt": "2026-08-16T14:22:03.000Z", "participantMinutes": 2 }

Encerre sempre ao terminar o teste. O POST /end apaga a sala no provedor na hora; sem ele, a sala fica viva pelo emptyTimeout inteiro — 600 segundos no padrão — e paga franquia por isso.

Credenciais de staging, conforme AMBIENTES.md. Produção não tem a organização b0000000-…-0001 usada em staging e nos testes ponta a ponta; consulte iam.organizations no ambiente alvo antes de montar qualquer smoke.

Existe um smoke versionado e executável que cobre esse caminho inteiro mais os casos de erro: bun scripts/rooms-smoke.ts --env=prod, com --media e --recording como opções deliberadamente não padrão. Veja o runbook §7.

Diagnosticar transcript vazio

Objetivo: descobrir por que GET /sessions/:id/transcript volta sem nada.

São quatro causas possíveis, e elas se checam em ordem — o desenho é a mesma sequência de cima para baixo:

flowchart TD
  A["transcript vazio"] --> B{"a sessão pediu<br/>transcriptionEnabled?"}
  B -->|não| B1["o agente nunca foi despachado<br/>não há como ligar depois — crie outra sessão"]
  B -->|sim| C{"webhook do LiveKit<br/>cadastrado no projeto?"}
  C -->|não| C1["zero eventos: a sessão não vira live,<br/>o agente não é despachado,<br/>a gravação não começa"]
  C -->|sim| D{"worker de pé<br/>e recebeu o job?"}
  D -->|não| D1["suba o rooms-agent-worker<br/>e confira o log"]
  D -->|sim| E{"ROOMS_SCRIBE_AGENT_NAME<br/>igual nos dois lados?"}
  E -->|não| E1["job despachado para um pool sem worker"]
  E -->|sim| F["veja as armadilhas de pool compartilhado"]

Na ordem, e pare no primeiro que falhar:

1. A sessão pediu transcrição?

curl -s "$BASE/rooms/api/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '{transcriptionEnabled, status}'

curl -s "$BASE/rooms/api/v1/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '{transcriptionEnabled, status}'

Esperado: transcriptionEnabled: true. Se for false, o agente nunca foi despachado, e não há como ligar depois — crie outra sessão.

2. O webhook do LiveKit está cadastrado no projeto?

Sem ele o Rooms recebe zero eventos: a sessão não vira live sozinha, o agente nunca é despachado e a gravação nunca começa. O cadastro é só pelo painel do LiveKit Cloud, em Settings → Webhooks, apontando para:

https://<host>/rooms/livekit/webhooks

https://<host>/rooms/livekit/webhooks

O vídeo continua funcionando sem isso, o que torna a falha silenciosa.

3. O worker está de pé e recebeu o job?

docker service logs bb-production_rooms-agent-worker --since 5m | grep transcribing

docker service logs bb-production_rooms-agent-worker --since 5m | grep transcribing

Esperado, uma linha por faixa de áudio assinada:

scribe: transcribing track TR_... from host (host) @ 16000Hz/1ch model=nova-3 lang=pt-BR

scribe: transcribing track TR_... from host (host) @ 16000Hz/1ch model=nova-3 lang=pt-BR

4. Os dois lados concordam no nome do agente?

ROOMS_SCRIBE_AGENT_NAME precisa ter o mesmo valor no serviço rooms (que despacha) e no rooms-agent-worker (que se registra). Divergir significa job despachado para um pool sem worker.

Armadilhas. Se dois ambientes compartilham o mesmo projeto LiveKit e o mesmo nome de agente, os workers caem no mesmo pool e o do ambiente errado pega o job. Ele grava RoomUtterance com um sessionId que não existe no banco dele, viola a chave estrangeira e a transcrição não sai — nos dois ambientes, em cerca de metade das reuniões. Nome distinto por ambiente resolve; projeto separado por ambiente continua sendo o recomendado (runbook §2).

Recuperar uma gravação que parece perdida

Objetivo: obter o MP4 quando GET /recording responde RECORDING_NOT_READY.

A própria chamada de leitura já tenta a reconciliação: se não há gravação completed, o serviço consulta o provedor pelo egressId e persiste o estado terminal. Por isso o procedimento é chamar duas vezes — a primeira reconcilia, a segunda devolve a URL.

sequenceDiagram
  participant U as "você"
  participant Rooms as "serviço rooms"
  participant LK as "LiveKit"
  participant DB as "PostgreSQL"

  U->>Rooms: "GET /sessions/:id/recording (1ª vez)"
  Rooms->>DB: "procura gravação completed"
  DB-->>Rooms: "só uma linha em active"
  Rooms->>LK: "getRecordingResult(egressId)"
  LK-->>Rooms: "estado terminal + bucketKey"
  Rooms->>DB: "persiste completed"
  Rooms-->>U: "404 RECORDING_NOT_READY"
  U->>Rooms: "GET /sessions/:id/recording (2ª vez)"
  Rooms->>DB: "agora há completed com bucketKey"
  Rooms-->>U: "200 com URL assinada"

1. Primeira chamada — reconcilia

curl -s "$BASE/rooms/api/v1/sessions/$SESSION_ID/recording" \
  -H "Authorization: Bearer $TOKEN" | jq

curl -s "$BASE/rooms/api/v1/sessions/$SESSION_ID/recording" \
  -H "Authorization: Bearer $TOKEN" | jq

Esperado: ainda 404 RECORDING_NOT_READY, mas o estado terminal já foi persistido.

2. Segunda chamada — devolve a URL

curl -s "$BASE/rooms/api/v1/sessions/$SESSION_ID/recording" \
  -H "Authorization: Bearer $TOKEN" | jq '{status, durationMs, expiresIn}'

curl -s "$BASE/rooms/api/v1/sessions/$SESSION_ID/recording" \
  -H "Authorization: Bearer $TOKEN" | jq '{status, durationMs, expiresIn}'

Esperado:

{ "status": "completed", "durationMs": 726000, "expiresIn": 3600 }

{ "status": "completed", "durationMs": 726000, "expiresIn": 3600 }

Armadilhas.

• Se o egress ainda está rodando de verdade, a consulta devolve "em andamento" e nada muda. Espere o fim da chamada.
• Falha na consulta ao provedor é engolida de propósito, para que uma indisponibilidade do LiveKit não derrube a leitura de uma gravação que já esteja completed. O sintoma é o mesmo 404 — olhe o log do serviço para distinguir.
• Um registro completed sem bucketKey responde 404 igual. Não há o que assinar.

Reduzir o desperdício de franquia

Objetivo: parar de pagar sala vazia.

# no ambiente do serviço rooms
ROOMS_EMPTY_TIMEOUT_SECONDS=90    # staging usa 90; produção fica em 600 de propósito
ROOMS_MAX_PARTICIPANTS=4

# no ambiente do serviço rooms
ROOMS_EMPTY_TIMEOUT_SECONDS=90    # staging usa 90; produção fica em 600 de propósito
ROOMS_MAX_PARTICIPANTS=4

E, no fluxo da aplicação, sempre POST /sessions/:id/end ao terminar.

Armadilhas.

• Produção fica no padrão de 600 segundos de propósito: é a janela de reconexão de uma reunião real. Baixar é decisão de produto, não de infraestrutura.
• Valor inválido na variável (vazio, negativo, não inteiro) é ignorado e cai no padrão. Isso é deliberado — repassar NaN ao LiveKit deixaria salas órfãs consumindo franquia.
• Com transcrição ligada, a sala não fecha sozinha enquanto o agente estiver dentro. O POST /end é o que encerra.

Consumir os eventos da sala em outro sistema

O Rooms publica quatro eventos públicos no stream iam-events, entregues por assinatura de webhook através do Webhooks Engine:

Armadilhas.

• Todo evento carrega metadata.organizationId. Sem ele o consumidor de webhook descarta o evento — é o que amarra o evento ao tenant.
• session.ended é emitido uma vez só, guardado por uma marca em metadata.sessionEndedEmittedAt da própria sessão. Reentrega do webhook do LiveKit não duplica.
• A emissão é do tipo dispare-e-esqueça: falha ao publicar é registrada em log e não derruba a chamada de vídeo. Se o seu processo depende do evento, reconcilie por consulta.

Encerrar sessões esquecidas

Sessões abandonadas ficam live até o room_finished chegar.

O Rooms não usa nenhum MODULE_*_URL além do IAM — não há chamada de fachada para outros building blocks.

flowchart TD
  CAL["Calendar"] -->|agenda| APP["sua aplicação"]
  APP -->|"cria sessão"| ROOMS["Rooms"]
  IAM["IAM"] -->|"token com organizationId<br/>ROOMS_READ / ROOMS_WRITE"| ROOMS
  ROOMS -->|MP4| FS["File Storage<br/>(seu S3)"]
  ROOMS -->|"rooms.v1.utterance.finalized<br/>rooms.v1.session.ended"| AI["AI Engine<br/>resumo e extração"]
  FS -->|transcript e gravação| AI
  AI --> DP["Decision Platform"]
  DP --> WH["Webhooks Engine"]
  WH --> CLI["sistema do cliente"]
  ROOMS -.->|"quem leu gravação e transcrição"| AUD["Audit Trail"]

Este é o argumento comercial em uma imagem: a videochamada não é um produto isolado, é uma etapa. O que entra pela chamada sai como dado estruturado para o resto da esteira, com a mesma identidade e a mesma organização do começo ao fim.

Variáveis de ambiente — serviço rooms

Variáveis de ambiente — processo rooms-agent-worker

Dependências de infraestrutura

Limites

Catálogo de erros

Observabilidade

• GET /rooms/health devolve nome e versão. Não testa LiveKit nem Deepgram.
• Todo handler de webhook registra em log o motivo de ignorar um evento — sala desconhecida, campo faltando, tipo não tratado. A rota sempre responde 200.
• O worker registra a linha scribe: transcribing track ... por faixa de áudio assinada, com taxa, modelo e idioma. É a confirmação mais rápida de que a transcrição está viva.
• Falha de despacho do agente e de início de gravação aparece como error no log do serviço rooms, marcada como não fatal.
• Para auditar consumo no provedor: ListRooms mostra salas abertas e há quanto tempo; ListEgress mostra gravações e permite achar as que não estão em estado terminal. O consumo agregado só aparece no painel do LiveKit — a API não expõe.

Operação em produção

O runbook de produção cobre o que não cabe aqui: procedimento de implantação cirúrgica, migrações, DNS e TLS com router isolado no Traefik, o smoke de mídia ponta a ponta com áudio sintético, o mapa de franquia e as armadilhas já pagas. Leia antes de mexer em produção.

O ponto central: gravação e transcrição são dado pessoal, e voz é dado biométrico comportamental. Uma sessão com recordingEnabled: true produz vídeo e áudio de uma pessoa identificada. Uma sessão com transcriptionEnabled: true produz o conteúdo literal do que ela disse. Os dois são tratamento de dado pessoal sob a LGPD, e a base legal precisa existir antes de a chamada começar — não depois.

Consentimento, no caminho crítico

O convidado só entra se enviar lgpdAccepted: true, e o schema exige o literal true. A data do aceite é gravada em RoomParticipant.lgpdAcceptedAt, por participante. Não existe caminho de código em que alguém entre pelo link sem esse registro. Duas ressalvas honestas:

• O aceite do host é implícito. Quem cria a sessão também recebe lgpdAcceptedAt preenchido, sem tela de aceite — a premissa é que quem criou sabe que a chamada existe. Se a sua operação exige aceite explícito do operador, colete na sua interface.
• O aceite é um booleano, não um texto versionado. O sistema registra que houve aceite e quando, não a qual texto a pessoa aceitou. Se a sua exigência é provar o conteúdo do termo, guarde a versão do seu lado e amarre pelo sessionId.

Isolamento entre tenants

Toda rota autenticada aplica requireOrganization, e toda leitura de sessão, transcrição e gravação passa por RoomSessionService.getSession, que compara session.organizationId com o do token e devolve 404 — não 403 — quando difere. A escolha do 404 é deliberada: 403 confirmaria que a sessão existe. O nome da sala no provedor também carrega a organização (org_<organizationId>_<sessionId>), o que torna qualquer evento rastreável até o tenant.

flowchart TD
  A["GET /sessions/:id/transcript<br/>com token da org B"] --> B["authMiddleware"]
  B --> C["requirePermission(ROOMS_READ)"]
  C --> D["requireOrganization"]
  D --> E["RoomSessionService.getSession"]
  E --> F{"session.organizationId<br/>== org do token?"}
  F -->|não| G["404 NOT_FOUND<br/>não 403 — 403 confirmaria que existe"]
  F -->|sim| H["devolve os trechos"]

A rota pública de entrada

POST /join/:joinCode não exige token — é o ponto de entrada do cliente final. As proteções são três: o código é gerado aleatoriamente e é único; ele tem prazo de validade próprio, definido na criação; e há limite de 20 tentativas por minuto por IP. Use joinCodeTtlHours curto para atendimento agendado — um código de 168 horas é um link válido por uma semana.

Autenticidade do webhook

POST /livekit/webhooks é público por necessidade: quem chama é o LiveKit, não um usuário. A confiança vem da assinatura, verificada pelo WebhookReceiver contra o corpo cru recebido. Assinatura ausente ou inválida responde 401 e nada é processado.

Gravação

O MP4 é escrito pelo egress do LiveKit direto no seu bucket S3, com as credenciais que você configurou — o arquivo nunca passa pela nossa infraestrutura. A leitura sai por URL assinada com expiração; não há endpoint que devolva o arquivo. O caminho no bucket inclui a organização: rooms/recordings/<organizationId>/<sessionId>.mp4.

Retenção

Não há política automática de retenção. Sessões, participantes, trechos transcritos e registros de gravação permanecem no banco indefinidamente, e o MP4 permanece no S3 até que a política do seu bucket o remova. Isso é uma lacuna consciente e está na §15. Para atender a pedido de eliminação hoje, o caminho é manual: apagar a RoomSession — RoomParticipant, RoomUtterance e RoomRecording caem junto por cascata — e remover o objeto do S3 separadamente, porque o banco não o apaga.

flowchart TD
  A["pedido de eliminação do titular"] --> B["apagar a RoomSession"]
  B --> C["RoomParticipant"]
  B --> D["RoomUtterance"]
  B --> E["RoomRecording"]
  C -.->|cascata| F["removidos junto"]
  D -.->|cascata| F
  E -.->|cascata| F
  A --> G["remover o objeto do S3<br/>SEPARADAMENTE — o banco não o apaga"]

O que sai da sua infraestrutura

O áudio da sala trafega pelo LiveKit e, quando a transcrição está ligada, é enviado à Deepgram para reconhecimento de fala. Isso são dois operadores terceiros no fluxo de dado pessoal e precisa estar no seu inventário de tratamento. Se essa transferência não for aceitável, transcriptionEnabled: false mantém o áudio fora da Deepgram — e o servidor LiveKit é Apache 2.0, o que abre o caminho de auto-hospedagem para tirar também o vídeo da nuvem de terceiro.

flowchart LR
  P["voz e imagem do participante"] --> LK["LiveKit<br/>operador terceiro"]
  LK -->|"sempre"| M["mídia da sala"]
  LK -->|"só com transcriptionEnabled: true"| DG["Deepgram<br/>operador terceiro"]
  LK -->|"só com recordingEnabled: true"| S3["seu bucket S3<br/>(sua infraestrutura)"]
  DG --> T["texto transcrito<br/>volta e é gravado no seu Postgres"]

Credenciais

As chaves do LiveKit e da Deepgram vivem em variável de ambiente, guardadas com SOPS (SECRETS-SOPS-REFERENCE.md). Editar o arquivo de ambiente no servidor não persiste: toda implantação sobrescreve.

O meu cliente precisa instalar alguma coisa ou criar conta?

Não. Ele abre o link com o código, digita o nome, marca o aceite de gravação e entra pelo navegador. A rota POST /join/:joinCode é pública e não exige token. O que você precisa construir é a tela — o Rooms devolve token e serverUrl para o SDK cliente do LiveKit.

Tem agente de IA na sala?

Tem um agente, e ele só transcreve. Ele entra na sala como participante, assina apenas o áudio, manda para o reconhecimento de fala e grava cada trecho finalizado. Não há LLM no laço, ele não responde e não fala. Um agente conversacional é possível sobre a mesma base — o framework LiveKit Agents suporta — mas hoje não existe. Não prometa isso a cliente (§15).

A transcrição funciona bem em português?

Funciona, e isso foi validado em produção, não em laboratório: o teste de aceitação do rollout produziu 17 trechos com o texto correto, incluindo um código de verificação combinado antes (runbook §8). O modelo padrão é o nova-3 da Deepgram e o idioma vem da sessão, com pt-BR como padrão.

Onde fica a gravação?

No seu bucket S3. O egress do LiveKit escreve o MP4 direto lá, com as suas credenciais, em rooms/recordings/<organizationId>/<sessionId>.mp4. O arquivo nunca passa pela nossa infraestrutura. Para baixar, GET /sessions/:id/recording devolve URL assinada com expiração.

Quanto custa deixar a gravação ligada?

Muito mais do que parece, e é a resposta mais importante desta seção. A gravação exige transcodificação, e essa é a franquia mais apertada do provedor por uma ordem de grandeza. Em staging, testes casuais consumiram 31,6 dos 60 minutos mensais, enquanto vídeo e transcrição ficaram na casa de 1% das franquias deles (runbook §9). Deixe recordingEnabled: false salvo quando a gravação for o objetivo.

Por que a sala continua viva depois que todo mundo saiu?

Por causa do emptyTimeout, que no padrão é 600 segundos. É uma janela de reconexão deliberada para reunião real — cair a internet não deve encerrar o atendimento. O custo é que sala abandonada paga esses 10 minutos. Sempre chame POST /sessions/:id/end ao terminar; para ambiente de teste, baixe ROOMS_EMPTY_TIMEOUT_SECONDS.

Posso usar meu próprio projeto LiveKit, ou hospedar o servidor?

Hoje não, pela API. O provedor é configurado por variável de ambiente e vale para o deployment inteiro. A tabela RoomProviderConfig prevê provedor por organização, mas nenhum código a lê (§15). Como o servidor LiveKit é Apache 2.0, auto-hospedar é tecnicamente viável — e faz sentido econômico justamente porque o gargalo é a gravação, que vira CPU sua em vez de franquia. Mas é uma mudança de implantação, não uma configuração de cliente.

Dá para ter dois convidados na mesma sala?

Hoje não. A identidade do convidado é fixa em guest, então uma segunda pessoa com o mesmo código assume a mesma identidade e o LiveKit derruba a conexão anterior. A sala suporta 4 participantes, mas hoje só há um host e um convidado distinguíveis.

Quanto tempo os dados ficam guardados?

Indefinidamente. Não há política automática de retenção (§14 e §15). Transcrição, participantes e registros de gravação ficam no banco, e o MP4 fica no S3 até que a política do seu bucket o remova. Para atender a pedido de eliminação, apague a RoomSession — o resto cai por cascata — e remova o objeto do S3 separadamente. Se a sua operação é regulada, defina essa política antes de entrar em produção.

A transcrição sai sozinha ou preciso pedir?

Sai sozinha, desde que três coisas estejam certas: a sessão foi criada com transcriptionEnabled: true, o webhook do LiveKit está cadastrado no projeto, e o rooms-agent-worker está de pé com o mesmo ROOMS_SCRIBE_AGENT_NAME do serviço. Faltando qualquer uma, o vídeo funciona e a transcrição não — a falha é silenciosa. A receita de diagnóstico está na §11.

_{Padrão: PADRAO-DOCUMENTACAO.md · Índice: INDEX.md · Operação: runbook de produção}