Conector BOOM: Signals

O conector BOOM expõe o Sensor Signals por quatro tools. Elas seguem as mesmas regras da tela em Sensores > Signals: o que a tela recusa, o conector também recusa.

O conector aceita JWT (eyJ…) e token OAuth (mct_…). Com OAuth, o companyId é opcional. Um companyId de outra empresa retorna 401.

Cancelar e excluir Signals não estão disponíveis no conector. Seguem pelo suporte.

Tools

Tool	Método e caminho	O que faz
`core_signals_list`	`GET /v2/signals`	Lista os Signals, com status, ciclo, datas, campos editáveis e conversão
`core_signals_get`	`GET /v2/signals/{signalId}`	Detalhe completo: perguntas, conversão por cluster, relatório e análises da IA
`core_signals_create`	`POST /v2/signals`	Cria um Signal (Rascunho por padrão ou já Programado)
`core_signals_update`	`PUT /v2/signals/{signalId}`	Edita um Signal conforme o status

`core_signals_list`

Parâmetro	Descrição
`companyId`	UUID da empresa (opcional com OAuth)
`status`	`RASCUNHO`, `PROGRAMADO`, `ENVIADO` ou `ENCERRADO`
`cycleId`	Filtra por ciclo (UUID)
`page`	Página, começando em `0`
`size`	Itens por página (padrão `20`, máximo `100`)

A resposta traz statusCounts com o total por status. Esse total ignora o filtro de status.

`core_signals_get`

Parâmetro	Descrição
`signalId`	UUID do Signal (obrigatório)
`companyId`	UUID da empresa (opcional com OAuth)
`includeReport`	Inclui o Relatório e Análises da IA (padrão `true`)

O relatório só aparece depois do encerramento, com no mínimo 5 respostas, e só com as análises já publicadas. Rascunhos de análise nunca são retornados. Quando não há relatório, report.available vem false e report.reason explica o motivo. Respostas individuais e dados pessoais da audiência nunca são expostos. editableFields indica o que pode ser alterado no status atual.

O que cada perfil faz

Perfil	Listar e consultar	Criar e editar
Admin Cliente	Todos os Signals	Sim
RH Estratégico	Todos os Signals	Sim
RH Business Partner	Somente os que criou	Sim, só com colaboradores e clusters da própria área
GPS Admin Cliente	Erro de permissão	Não
Liderança	Erro de permissão	Não

Criar e editar

core_signals_create e core_signals_update seguem as quatro etapas da tela.

Etapa	Campos
Pesquisa	`name` (até 100 caracteres), `description`, `cycleId`
Perguntas	`questions`, `questionGroups`, `welcomeScreen`, `thankYouScreen`
Disparo	`sendDate`, `endDate`
Audiência	`employeeIds`, `clusters`, `audienceMode`

Na criação, name e cycleId são obrigatórios. O parâmetro draft controla o resultado:

draft=true (padrão): salva como Rascunho, em qualquer etapa, sem exigir os demais campos e sem disparar envio.
draft=false: finaliza e o Signal vira Programado. O time BOOM é notificado, como na tela.

Para finalizar, o servidor exige:

ao menos 1 pergunta;
ao menos 1 colaborador na audiência;
sendDate com 24 horas úteis de antecedência (sábado e domingo não contam, feriados não são considerados, horário de Brasília);
endDate depois do envio.

Datas

Use ISO 8601. Sem fuso (2026-11-10T09:00:00) vale o horário de Brasília. Com fuso (Z ou +hh:mm), o servidor converte para Brasília.

O que cada status permite editar

Status	Edição
`RASCUNHO`	Tudo: perguntas, grupos, telas, datas e audiência. Passe `draft=false` para finalizar
`PROGRAMADO`	`name`, `description`, `cycleId`, `endDate` e audiência. `sendDate` só com mais de 24 horas úteis até o envio
`ENVIADO`	Os mesmos de Programado, sem `sendDate`. Não pode mudar para um ciclo encerrado
`ENCERRADO`	Não edita

Enviar questions ou telas fora do Rascunho é recusado. Não é possível voltar para Rascunho. Programado e Enviado não podem ficar com audiência vazia. Em core_signals_update, campos omitidos são preservados.

Audiência

Envie employeeIds (UUIDs de colaboradores) e/ou clusters (clusterType e clusterId). Os clusters são expandidos para os colaboradores Ativos e Afastados do cluster. Desligados não entram.

`audienceMode`	Efeito
`REPLACE` (padrão)	Substitui a audiência atual
`ADD`	Acrescenta aos membros atuais

Se employeeIds e clusters forem omitidos, a audiência não muda. Tipos de cluster: BUSINESS_UNIT, DIRECTORATE, DEPARTMENT, ALLOCATION e WHITE_LABEL_A a WHITE_LABEL_E.

Perguntas

Cada item de questions aceita estes campos.

Campo	Descrição
`text`	Texto da pergunta (obrigatório)
`description`	Texto de apoio
`questionType`	Um dos 10 tipos (obrigatório). Veja a tabela abaixo
`required`	Resposta obrigatória
`questionOrder`	Posição (1, 2, …). Sem ela, vale a ordem da lista. Não pode repetir
`questionKey`	Chave estável, usada pela lógica condicional. Omitida em pergunta nova, é gerada
`surveyQuestionId`	UUID de uma pergunta existente. Ao editar um Rascunho, mantém a identidade da pergunta
`questionGroupKey`	`key` de um grupo de `questionGroups` ao qual a pergunta pertence
`showOnlyByCondition`	A pergunta só aparece quando alguma opção a aponta via `goTo`
`questionOptions`	Opções (escolhas) ou colunas (matrizes)
`questionOptionsOrder`	`FIXED` (padrão) ou `RANDOM`

Os 10 tipos de pergunta

`questionType`	Tela	Campos específicos
`TEXT_SHORT`	Texto curto
`TEXT_LONG`	Texto longo
`SINGLE_CHOICE`	Escolha única	`questionOptions` (mínimo 2), `goTo` por opção
`MULTIPLE_CHOICE`	Múltipla escolha	`questionOptions` (mínimo 2), `goTo` por opção, `minSelectableOptions`, `maxSelectableOptions`
`NUMERIC_RATING`	Avaliação numérica	`ratingMin` (obrigatório), `ratingMax`, `ratingLabelMin`, `ratingLabelMax`
`SLIDER`	Controle deslizante	`ratingMin` (padrão 0), `ratingMax` (padrão 10), `sliderStep`, `sliderStartPosition`, `sliderShowValue`
`ENPS`	eNPS	Faixa de 0 a 10 e rótulos fixos
`NUMBER`	Número
`MATRIX_SINGLE`	Matriz única	`matrixRows`, `questionOptions` como colunas. Uma coluna por linha
`MATRIX_MULTIPLE`	Matriz múltipla	`matrixRows`, `questionOptions` como colunas. Várias colunas por linha, com `minSelectableOptions` e `maxSelectableOptions` por linha

Avaliação numérica e slider

ratingMax precisa ser maior que ratingMin.
sliderStep (padrão 1) precisa dividir ratingMax - ratingMin.
sliderStartPosition é MIDDLE (padrão) ou START. sliderShowValue é true por padrão.

Escolhas

SINGLE_CHOICE e MULTIPLE_CHOICE exigem no mínimo 2 opções.
Cada opção tem text e, opcionalmente, id (gerado se omitido) e goTo.

Matrizes

Item	Limite
Linhas (`matrixRows`)	2 a 20, cada uma com `text` e `id` opcional
Colunas (`questionOptions`)	2 a 10, com `id` gerado se omitido
`matrixRowsOrder`	`FIXED` (padrão) ou `RANDOM`

Mínimo e máximo de respostas

minSelectableOptions e maxSelectableOptions valem só em MULTIPLE_CHOICE e, por linha, em MATRIX_MULTIPLE. Os outros tipos recusam os campos.

Regra	Valor
Mínimo	`0` ou mais. Não passa do total de opções (ou colunas) nem do máximo
Máximo	`1` ou mais. Não passa do total de opções (ou colunas)
Mínimo e máximo juntos	O máximo não pode ser menor que o mínimo
Matriz múltipla obrigatória	O mínimo por linha precisa ser pelo menos `1`

Grupos de perguntas

questionGroups agrupa perguntas em blocos. Cada pergunta entra num grupo pelo questionGroupKey, que é o key do grupo.

Campo	Descrição
`key`	Chave do grupo (obrigatório)
`title`	Título do grupo
`message`	Texto do grupo
`buttonText`	Texto do botão do grupo
`questionsOrder`	`FIXED` ou `RANDOM`: ordem das perguntas dentro do grupo

Em core_signals_update, questionGroups só é aceito em Rascunho e substitui os grupos. Omitido, preserva os atuais.

Lógica condicional (`goTo`)

Em SINGLE_CHOICE e MULTIPLE_CHOICE, cada opção pode ter um goTo que decide para onde o respondente vai ao escolher aquela opção.

Valor de `goTo`	Destino
`questionKey` de uma pergunta	Pula para aquela pergunta
`group:<key do grupo>` (ou só a `key` do grupo)	Segue para o grupo inteiro
`END`	Encerra a pesquisa
Omitido ou `NEXT`	Segue a ordem normal

Regras:

A lógica só avança. Um goTo que aponta para pergunta ou grupo anterior (ou para o próprio grupo da pergunta) é recusado.
goTo em outros tipos de pergunta é recusado.
Não vale dentro de um grupo com ordem RANDOM, nem apontando para uma pergunta dentro dele. Um grupo RANDOM inteiro pode ser destino, com group:<key>.
showOnlyByCondition exige que alguma opção leve até a pergunta, e a primeira pergunta não pode ser condicional.
Em edição de Rascunho, inclua surveyQuestionId das perguntas mantidas: elas preservam questionKey, grupo, condição e goTo. Um goTo omitido preserva o valor salvo.

Exemplo

{
  "name": "Clima da equipe",
  "cycleId": "00000000-0000-7000-8000-000000000001",
  "draft": true,
  "questionGroups": [
    { "key": "detalhes", "title": "Conte mais", "questionsOrder": "FIXED" }
  ],
  "questions": [
    {
      "questionKey": "satisfeito",
      "text": "Você está satisfeito com o time?",
      "questionType": "SINGLE_CHOICE",
      "required": true,
      "questionOptions": [
        { "text": "Sim", "goTo": "END" },
        { "text": "Não", "goTo": "group:detalhes" }
      ]
    },
    {
      "questionKey": "motivos",
      "questionGroupKey": "detalhes",
      "showOnlyByCondition": true,
      "text": "O que mais pesa?",
      "questionType": "MULTIPLE_CHOICE",
      "minSelectableOptions": 1,
      "maxSelectableOptions": 2,
      "questionOptions": [
        { "text": "Carga de trabalho" },
        { "text": "Comunicação" },
        { "text": "Liderança" }
      ]
    }
  ]
}

Telas de boas-vindas e agradecimento

Objeto	Campos
`welcomeScreen`	`title`, `message`, `buttonText`, `confirmationText`
`thankYouScreen`	`title`, `message`

Pergunte ao Claude

“Quais Signals estão em rascunho?”
“Crie um rascunho de Signal com uma pergunta de escolha única que encerra a pesquisa se a resposta for Sim.”
“Quantos colaboradores já responderam o Signal de clima?”

Visão geral

GPS

Sensores

Cadastros

Tools

`core_signals_list`

`core_signals_get`

O que cada perfil faz

Criar e editar

Datas

O que cada status permite editar

Audiência

Perguntas

Os 10 tipos de pergunta

Avaliação numérica e slider

Escolhas

Matrizes

Mínimo e máximo de respostas

Grupos de perguntas

Lógica condicional (`goTo`)

Exemplo

Telas de boas-vindas e agradecimento

Pergunte ao Claude

Tools

core_signals_list

core_signals_get

O que cada perfil faz

Criar e editar

Datas

O que cada status permite editar

Audiência

Perguntas

Os 10 tipos de pergunta

Avaliação numérica e slider

Escolhas

Matrizes

Mínimo e máximo de respostas

Grupos de perguntas

Lógica condicional (goTo)

Exemplo

Telas de boas-vindas e agradecimento

Pergunte ao Claude

`core_signals_list`

`core_signals_get`

Lógica condicional (`goTo`)