WebSocket

Introdução

O PalcoTimer usa WebSocket para sincronização em tempo real entre todos os dispositivos conectados. Qualquer alteração (play, pause, mudança de timer, mensagem) é propagada instantaneamente.

Conectando

Conecte ao WebSocket usando a URL:

wss://app.palcotimer.com/ws/{roomId}?output={tipo}&name={nome}

Mensagens Cliente → Servidor

Solicitar estado

{
  "type": "request_state"
}

Ping (manter conexão)

{
  "type": "ping"
}

Controles de playback

// Play
{ "type": "control", "action": "play" }

// Pause
{ "type": "control", "action": "pause" }

// Stop
{ "type": "control", "action": "stop" }

// Reset
{ "type": "control", "action": "reset" }

// Próximo timer
{ "type": "control", "action": "next" }

// Timer anterior
{ "type": "control", "action": "previous" }

// Ir para timer específico
{ "type": "control", "action": "go_to", "timer_id": "uuid" }

// Adicionar tempo (ms)
{ "type": "control", "action": "add_time", "value": 60000 }

// Definir tempo (ms)
{ "type": "control", "action": "set_time", "value": 300000 }

Modos de exibição

// Ativar/desativar blackout
{ "type": "control", "action": "blackout" }
{ "type": "control", "action": "stop_blackout" }

// Ativar/desativar flash
{ "type": "control", "action": "flash" }
{ "type": "control", "action": "stop_flash" }

// Ativar/desativar focus (apenas mensagem)
{ "type": "control", "action": "focus" }
{ "type": "control", "action": "stop_focus" }

Mensagens

// Mostrar mensagem
{ "type": "control", "action": "show_message", "timer_id": "message_uuid" }

// Esconder mensagem
{ "type": "control", "action": "hide_message" }

Do palco para o servidor

Só são aceitos de uma conexão output=viewer, a tela do palestrante. De qualquer outro tipo de saída são ignorados. O tipo de saída é definido pelo servidor na conexão, nunca pelo payload. Nenhum dos dois altera o cronômetro.

{ "type": "ack_message", "message_id": "message_uuid" }

{ "type": "send_signal", "signal_key": "slide_issue" }

ack_message: o palestrante confirma a mensagem exibida. message_id é o id da mensagem; id inválido, repetido na mesma exibição, de mensagem que não está no ar ou com ack_enabled desligado é descartado em silêncio.

send_signal: aciona um sinal pré-definido pela chave (signal_key). No máximo 1 sinal a cada 3 segundos por conexão.

Mensagens Servidor → Cliente

Todo quadro do servidor tem o campo type e, no mesmo nível, os campos do payload. A tabela abaixo é a lista dos eventos que existem sempre, sem depender de recurso ligado no servidor, mais os de comunicação régie-palco, que só existem quando o palco está ligado na sala e dizem isso na própria descrição. Um ? no payload marca campo que pode vir ausente.

Estado da sala

{
  "type": "room",
  "room": { "id": "...", "name": "...", ... },
  "timers": [ ... ],
  "messages": [ ... ],
  "playback": {
    "state": "running",
    "current_timer_id": "uuid",
    "elapsed_ms": 60000,
    "blackout": false,
    "flash": false,
    "focus": false
  },
  "server_time": 1704067200000
}

Status de playback

{
  "type": "playback_status",
  "state": "running",
  "timer_id": "uuid",
  "elapsed_ms": 65000,
  "duration_ms": 300000,
  "server_time": 1704067200000,
  "blackout": false,
  "flash": false,
  "focus": false
}

Atualização de timer

{
  "type": "timer_update",
  "timer": {
    "action": "update",
    "timer": { ... }
  }
}

Pong

{
  "type": "pong",
  "server_time": 1704067200000
}

Os demais eventos

Formato dos eventos que não têm exemplo próprio acima.

// Timer excluído: vem o id, não o timer
{ "type": "timer_delete", "timer": { "action": "delete", "id": "uuid" } }

// Mensagem criada, editada e excluída
{ "type": "message",        "message": { "action": "create", "message": { ... } } }
{ "type": "message_update", "message": { "action": "update", "message": { ... } } }
{ "type": "message_delete", "message": { "action": "delete", "id": "uuid" } }

// Todas as mensagens ocultadas de uma vez: action hide, sem corpo
{ "type": "message", "message": { "action": "hide" } }

// Modos do telão (o valor é o estado DEPOIS da mudança)
{ "type": "flash",    "flash": true }
{ "type": "blackout", "blackout": false }
{ "type": "focus",    "focus": true }

// Lista de conexões da sala; clients vem ausente quando a lista está vazia
{
  "type": "clients",
  "clients": [
    { "id": "uuid", "room_id": "uuid", "output_type": "viewer", "device_name": "Telao 1" }
  ]
}

// Recálculo da agenda de timers depois de um atraso
{
  "type": "schedule_update",
  "delay_ms": 300000,
  "original_end": "2026-01-01T12:30:00Z",   // opcional
  "projected_end": "2026-01-01T12:35:00Z",  // opcional
  "timers": [ ... ]
}

// Pedido de recarregar a página, para toda a sala
{ "type": "force_reload" }

// Erro; o texto vem em message ou em error, conforme o caso
{ "type": "error", "code": "FORBIDDEN",        "message": "..." }
{ "type": "error", "code": "CONNECTION_LIMIT", "message": "..." }
{ "type": "error", "code": "UNKNOWN_ACTION",   "error": "..." }

// Só para a conexão desconectada pelo administrador, logo antes de fechar
{ "type": "kicked", "message": "..." }

// Só na sala de demonstração, quando ela é reiniciada
{ "type": "demo_reset", "roomId": "uuid", "at": 1704067200000 }

Enquetes

Enquetes ao vivo (múltipla escolha, escala e nuvem de palavras) usam o mesmo WebSocket da sala. Os eventos poll_* abaixo são aditivos: um cliente que não os conhece pode ignorá-los com segurança, como já faz com qualquer tipo de mensagem desconhecido.

Novos campos no estado da sala

A mensagem type room, enviada ao conectar, ganha campos opcionais. Todos os campos que já existiam mantêm nome e formato.

{
  "type": "room",
  "room": { "id": "...", "name": "...", ..., "capabilities": { "polls": true } },
  "timers": [ ... ],
  "messages": [ ... ],
  "playback": { ... },
  "server_time": 1704067200000,
  "audience_stage": "poll",
  "poll": { "id": "uuid", "question": "...", "type": "multiple_choice", "status": "open", ... },
  "results": { "poll_id": "uuid", "status": "open", "total_votes": 12, "total_voters": 12, ... }
}

Eventos de enquete

Todos têm o campo type mais os campos do payload, no mesmo nível, como os demais eventos.

Quem recebe os números

O resultado agregado (campo results) vai para a sala toda somente enquanto a enquete está no telão, porque nesse caso os números já estão na tela grande. Fora do telão, results vai apenas para as telas de produção (controller e moderator). Isso vale para poll_results, para poll_closed e para o results do estado da sala.

Formato de poll e results

// poll
{
  "id": "uuid", "room_id": "uuid",
  "question": "...",
  "type": "multiple_choice",            // multiple_choice | scale | word_cloud
  "options": [{ "id": "...", "text": "..." }],                 // multiple_choice
  "scale": { "min": 1, "max": 5, "min_label": "...", "max_label": "..." },  // scale
  "word_cloud": { "max_words_per_voter": 3, "max_word_length": 30 },        // word_cloud
  "status": "open",                     // draft | open | closed
  "show_on_stage": true,
  "results_visibility": "always",       // always | after_vote | when_closed | never
  "position": 0,
  "created_at": "2026-01-01T12:00:00Z",
  "opened_at": "2026-01-01T12:05:00Z",  // opcional
  "closed_at": "2026-01-01T12:10:00Z",  // opcional
  "total_votes": 12
}

// results
{
  "poll_id": "uuid", "status": "open",
  "total_votes": 12, "total_voters": 12,
  "options": [{ "id": "...", "text": "...", "count": 7, "percent": 58.3 }],  // multiple_choice
  "scale": { "average": 3.8, "distribution": { "1": 0, "2": 1, "3": 4 } },  // scale
  "words": [{ "word": "...", "count": 5 }]                                   // word_cloud
}

// audience_stage: "none" | "poll"

Quiz ao vivo

O quiz ao vivo (perguntas de múltipla escolha com pontuação e ranking) usa o mesmo WebSocket da sala. Os eventos quiz_* são aditivos: um cliente que não os conhece pode ignorá-los com segurança, como já faz com qualquer tipo de mensagem desconhecido.

Novos campos no estado da sala

Com o quiz no telão, a mensagem type room ganha o campo opcional quiz — o mesmo formato do campo quiz de quiz_state — e audience_stage passa a aceitar o valor quiz. O telão tem um único espaço de conteúdo de plateia: enquete e quiz não convivem. Quando o quiz entra, a enquete que estava no ar sai com um poll_hidden e a pergunta em destaque do Q&A sai com um question_highlights_cleared.

Eventos do quiz

Todos têm o campo type mais os campos do payload, no mesmo nível, como os demais eventos.

Formato de quiz, question e entries

// quiz (campo quiz de quiz_state e do estado da sala)
{
  "id": "uuid", "title": "...",
  "status": "running",                  // draft | running | finished
  "stage": "question",                  // lobby | question | reveal | ranking | podium
  "question_index": 2, "question_count": 10, "participant_count": 48,
  "question": { ... },                  // só na etapa question
  "reveal": { "question_id": "uuid", "correct_option": 1, "distribution": [3, 9, 1, 0], "total_answers": 13 },
  "ranking": [ ... ]                    // só nas etapas ranking e podium
}

// question (sem gabarito)
{
  "id": "uuid", "index": 3, "total": 10,
  "text": "...", "options": ["...", "..."],
  "time_limit_ms": 30000,
  "opened_at": 1704067200000,           // epoch ms do relógio do servidor
  "deadline": 1704067230000
}

// entries (também é o campo entries de quiz_ranking e quiz_finished)
[
  { "position": 1, "quiz_participant_id": "uuid", "display_label": "...", "score": 2840, "correct_time_sum_ms": 18230 }
]

// audience_stage: "none" | "poll" | "quiz"

Perguntas da plateia (Q&A)

As perguntas enviadas pela plateia usam o mesmo WebSocket da sala. Não há variável de ambiente para o Q&A: ele é ligado nas configurações de cada sala (qa_enabled).

Eventos de pergunta

Todos têm o campo type mais os campos do payload, no mesmo nível, como os demais eventos.

Formato de question

// question
{
  "id": "uuid", "room_id": "uuid",
  "text": "...",
  "author_name": "...",                 // opcional
  "status": "pending",                  // pending | approved | rejected | answered
  "highlighted": false,
  "upvotes": 7,
  "created_at": "2026-01-01T12:00:00Z",
  "reviewed_at": "2026-01-01T12:01:00Z", // opcional
  "answered_at": "2026-01-01T12:05:00Z"  // opcional
}

Agenda enriquecida

A agenda pública enriquecida (palestrantes, trilhas, locais e mapa do evento) usa o mesmo WebSocket da sala, para o celular aberto da plateia refletir uma edição feita na régie sem recarregar a página.

Novo campo no estado da sala

Nas conexões que desenham a agenda (output=public_agenda e output=agenda), a mensagem type room ganha o campo opcional agenda, com exatamente o mesmo conteúdo de agenda_update, e room.capabilities.agenda_enriched vem verdadeiro. Nos demais tipos de saída o quadro é idêntico ao de sempre. O payload público não leva as notas privadas da régie, nem room_id, nem datas de criação.

O evento agenda_update

Emitido a cada edição da agenda feita na régie: criar, editar ou excluir palestrante, local ou mapa do evento, e gravar o bloco de agenda pública de uma sessão. Leva a agenda INTEIRA, não um delta: substitua o que você tem em memória pelo conteúdo recebido.

Campos de agenda

{
  "type": "agenda_update",
  "agenda": {
    "speakers": [
      {
        "id": "66666666-6666-4666-8666-666666666666",
        "name": "Ana Souza",
        "title_company": "CTO, Acme",       // opcional
        "bio": "Fala de plataformas.",      // opcional
        "photo_url": "https://cdn.exemplo/ana.jpg"  // opcional
      }
    ],
    "locations": [
      {
        "id": "77777777-7777-4777-8777-777777777777",
        "name": "Auditorio",
        "pin_x": 0.25,                      // opcional
        "pin_y": 0.75                       // opcional
      }
    ],
    "sessions": [
      {
        "timer_id": "22222222-2222-4222-8222-222222222222",
        "description": "Como escalamos o palco.",   // opcional
        "track": "Engenharia",                      // opcional
        "location_id": "77777777-7777-4777-8777-777777777777",  // opcional
        "speaker_ids": ["66666666-6666-4666-8666-666666666666"]
      }
    ],
    "event_map": { "image_url": "https://cdn.exemplo/planta.png" }  // opcional
  }
}

Sala sem dados de agenda

Uma sala que nunca preencheu a agenda — ou que teve tudo apagado — recebe o mesmo evento, com os três arrays vazios e sem event_map. Este é o payload mínimo:

{
  "type": "agenda_update",
  "agenda": {
    "speakers": [],
    "locations": [],
    "sessions": []
  }
}

Comunicação régie e palco

O palestrante, numa tela viewer no palco, pode confirmar que viu a mensagem no ar ("visto") e acionar sinais pré-definidos, como "problema no slide". A régie recebe os dois em tempo real pelo mesmo WebSocket da sala.

Campos novos no estado da sala

Só nas conexões controller e operator, e só com a função ligada, a mensagem type room ganha dois campos opcionais: message_acks (os "vistos" do ciclo atual da mensagem no ar, só com ack_enabled) e signals (os sinais das últimas 24 horas, os mais recentes primeiro, só com enabled na sala). Ficam ausentes quando vazios. room.capabilities.stage_signals vem verdadeiro. Nenhum campo existente muda; viewer, embed e agenda recebem o quadro de sempre.

{
  "type": "room",
  "room": { "capabilities": { "stage_signals": true } },
  "message_acks": [
    {
      "message_id": "aaaaaaaa-0000-4000-8000-00000000000a",
      "conn_id": "bbbbbbbb-0000-4000-8000-00000000000b",
      "device_name": "iPad Palco",
      "acked_at": "2026-10-08T20:52:03Z"
    }
  ],
  "signals": [
    {
      "id": "cccccccc-0000-4000-8000-00000000000c",
      "signal_key": "slide_issue",
      "label": "Problema no slide",
      "conn_id": "bbbbbbbb-0000-4000-8000-00000000000b",
      "device_name": "iPad Palco",
      "status": "new",
      "created_at": "2026-10-08T20:52:10Z"
    }
  ]
}

Formato dos eventos

device_name é o nome que o dispositivo informou: tem no máximo 60 caracteres e não traz caracteres de controle. É texto do usuário: mostre-o como texto, nunca como HTML. conn_id é gerado pelo servidor. O status do sinal é new ou acked; acked_at e acked_by_device só existem depois de atendido.

// message_ack
{
  "type": "message_ack",
  "message_id": "aaaaaaaa-0000-4000-8000-00000000000a",
  "conn_id": "bbbbbbbb-0000-4000-8000-00000000000b",
  "device_name": "iPad Palco",
  "acked_at": "2026-10-08T20:52:03Z"
}

// signal
{
  "type": "signal",
  "signal": {
    "id": "cccccccc-0000-4000-8000-00000000000c",
    "signal_key": "slide_issue",
    "label": "Problema no slide",
    "conn_id": "bbbbbbbb-0000-4000-8000-00000000000b",
    "device_name": "iPad Palco",
    "status": "new",
    "created_at": "2026-10-08T20:52:10Z"
  }
}

// signal_update (atendido pela régie)
{
  "type": "signal_update",
  "signal": {
    "id": "cccccccc-0000-4000-8000-00000000000c",
    "signal_key": "slide_issue",
    "label": "Problema no slide",
    "conn_id": "bbbbbbbb-0000-4000-8000-00000000000b",
    "device_name": "iPad Palco",
    "status": "acked",
    "created_at": "2026-10-08T20:52:10Z",
    "acked_at": "2026-10-08T20:52:40Z",          // só depois de atendido
    "acked_by_device": "Régie Principal"         // só depois de atendido
  }
}

Erros desta função

São quadros type error enviados SÓ à conexão que enviou o sinal, nunca à sala. Identifique-os pelo campo code.

// error (só ao emissor)
{ "type": "error", "code": "signal_rate_limited", "retry_after_ms": 2100 }

{ "type": "error", "code": "signal_unknown_or_inactive" }

signal_rate_limited: o anti-spam recusou o sinal. retry_after_ms diz quantos milissegundos faltam para poder enviar de novo.

signal_unknown_or_inactive: a chave não existe, está inativa ou os sinais estão desligados na sala. Não leva retry_after_ms.

Exemplo Completo

// JavaScript - Conectar e controlar
const ws = new WebSocket('wss://app.palcotimer.com/ws/ABC123?output=controller');

ws.onopen = () => {
  console.log('Conectado!');
  // Solicitar estado inicial
  ws.send(JSON.stringify({ type: 'request_state' }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'room':
      console.log('Estado da sala:', data);
      break;
    case 'playback_status':
      console.log('Playback:', data.state, data.elapsed_ms);
      break;
  }
};

// Controlar
function play() {
  ws.send(JSON.stringify({ type: 'control', action: 'play' }));
}

function pause() {
  ws.send(JSON.stringify({ type: 'control', action: 'pause' }));
}