Runbook - Fluxo padrão do Sagazchat

Manual operacional para configurar Configurações > Fluxo padrão no Sagazchat. Fluxos padrão sao disparados automaticamente por eventos do sistema (primeiro contato, inatividade, conversa finalizada, aniversario), sem o atendente precisar acionar.

Status: validado em 2026-05-11 na conta exemplo. Salvar+reverter capturado no canal exemplo (whatsappId=216, id=274). Conta voltou ao estado original (4 comboboxes vazios).

1. Onde fica

• Sidebar: Configurações > Fluxo padrão
• URL: https://app.sagazchat.com/flowdefault
• Endpoint backend: /flowdefault (mesmo nome).

2. Estrutura

Layout em duas colunas, igual a Horários:

• Esquerda: lista de canais conectados (cards).
• Direita: configuracao do canal selecionado.

3. Os 4 tipos de fluxo padrão

Apos selecionar um canal, o painel direito mostra 4 secoes, cada uma com um combobox Selecione um fluxo:

#	Tipo	Quando dispara	Texto exibido na UI
1	Fluxo de boas-vindas	Novo contato envia a primeira mensagem	”para novos contatos que não estão na sua lista e enviarem uma mensagem pela primeira vez”
2	Fluxo de resposta padrão	Cliente envia mensagem que nao bate palavra-chave configurada, apos periodo de inatividade (padrao 24h)	“quando o cliente enviar qualquer mensagem que não corresponda a uma palavra-chave configurada… apos o período de inatividade configurado”
3	Fluxo de conversa finalizada	Cliente cujo atendimento foi marcado como concluido envia nova mensagem	”quando um cliente, cujo atendimento já foi marcado como concluído, enviar uma nova mensagem”
4	Fluxo de aniversário	Dia do aniversario do contato (se a data estiver cadastrada)	“no dia do aniversário do contato, caso a informação esteja disponível no cadastro. O agendamento e efetuado exatamente no dia do aniversário para o horário definido de disparo, antes do horário comercial”

Falta no user-facing antigo: o Fluxo de aniversário existe no produto mas a doc anterior listava so 3 tipos. Adicionado.

3.1 Campos auxiliares

Alem dos 4 comboboxes:

• Horas (input numerico, ao lado do Fluxo de resposta padrão): periodo de inatividade. Padrao 24. Significa: o cliente precisa ficar X horas sem responder antes do fluxo disparar. Field name no payload: welcomeTime (nome desviante, ver § 5.2).
• Horario de disparo aniversario (input type=time, ao lado do Fluxo de aniversário): hora do dia em que o fluxo de aniversario dispara. Padrao 12:00:00. Field name: flowBirthdayTriggerTime.

4. Salvar

Botao Salvar verde no rodape (esta fora da viewport em telas comuns — precisa scroll). So depois de clicar nele a config persiste.

4.1 Endpoint validado

PUT https://backend.sagazchat.com/flowdefault
Authorization: Bearer <jwt>
Content-Type: application/json

4.2 Payload completo

{
  "id": 274,
  "whatsappId": 216,
  "waOficialId": null,
  "instagramId": null,
  "flowIdWelcome": 540,
  "flowIdPhrase": null,
  "welcomeTime": 24,
  "flowIdClosedChat": null,
  "flowIdBirthday": null,
  "flowBirthdayTriggerTime": "12:00:00"
}

Mapeamento UI → payload:

UI	Payload	Tipo
Fluxo de boas-vindas	flowIdWelcome	int OR null
Fluxo de resposta padrão	flowIdPhrase	int OR null
Fluxo de conversa finalizada	flowIdClosedChat	int OR null
Fluxo de aniversário	flowIdBirthday	int OR null
Horas (inatividade resposta padrão)	welcomeTime	int
Horario aniversário	flowBirthdayTriggerTime	”HH:MM:SS”

5. Quirks (importantes)

5.1 Botão Salvar fora da viewport

Em telas com altura padrao (1080), o botao Salvar fica em y=1227, abaixo da area visivel. page.mouse.click(x, y) no Playwright falha silenciosamente porque a coordenada esta fora do viewport. Soluções:

• Usar page.locator('button').filter({ hasText: /^Salvar$/ }).click() — locator do Playwright faz scroll automatico antes de clicar.
• OU rolar manualmente: await page.evaluate(() => document.querySelector('button[type=submit]')?.scrollIntoView()) antes de clicar.

Esse comportamento diferencia este modulo dos outros (Horarios, Variavel global, etc) onde o Salvar sempre estava visivel.

5.2 welcomeTime engana

O campo welcomeTime no payload NAO se refere ao Fluxo de boas-vindas — refere-se ao periodo de inatividade do Fluxo de resposta padrão. Nomenclatura do backend e enganosa. Na UI, o input “Horas” aparece logo abaixo de “Fluxo de resposta padrão”, confirmando o uso real.

5.3 Botão Clear (X) só visível em hover

O botao “X” do MUI Autocomplete (para limpar um combobox) so e visivel quando o mouse esta sobre o campo. Em Playwright, usar .click({ force: true }) ou hover() antes.

5.4 Salvar com tudo null = limpar

Para “desativar” um fluxo padrao, basta limpar o combobox correspondente e salvar. O backend grava null no campo e o disparador para de funcionar.

6. Acoes seguras e perigosas

Acao	Impacto	Regra
Abrir lista	Leitura	Seguro.
Selecionar canal	Carrega painel	Seguro.
Trocar fluxo no combobox	Apenas local	Seguro ate Salvar.
Clicar Salvar com config nova	Persiste — dispara para clientes reais	Confirmar antes; testar com numero pessoal.
Limpar combobox + Salvar	Desliga aquele fluxo padrao	Cuidado: contatos novos param de receber boas-vindas, por exemplo.
Mudar welcomeTime	Altera quando resposta padrao dispara	Cuidado com valores muito baixos (spam).

7. Diferenca para “Fluxo padrão” e outros disparadores

Disparador	Onde configura	Quando dispara
Fluxo padrão (Boas-vindas)	Configurações > Fluxo padrão > Boas-vindas	Primeiro contato com numero novo.
Fluxo padrão (Resposta padrão)	Configurações > Fluxo padrão > Resposta padrão	Mensagem fora de palavra-chave + apos N horas de inatividade.
Mensagem fora de horário (Horários)	Configurações > Horários > Ação	Cliente escreve fora do expediente do canal.
Resposta de IA (Assistente IA)	Conexões > kebab > Assistente IA	Antes da regra de horario; quando vinculado ao canal.
Disparo manual de fluxo	Bate Papo (atendente seleciona fluxo)	Atendente aciona.

Ordem de prioridade entre eles [a validar] — provavelmente IA > Boas-vindas > Resposta padrão > Conversa finalizada > Horarios. Confirmar com o administrador.

8. Pendencias

• Validar ordem de prioridade entre disparadores quando varios sao aplicaveis (ex: novo contato fora de horario).
• Confirmar comportamento se o fluxo selecionado for excluido depois (fluxo orfao).
• Capturar reposta do PUT /flowdefault (status + body).

9. Imagens

• public/media/nova-ui/fluxo-padrao-lista-canais.png
• public/media/nova-ui/fluxo-padrao-config-canal.png
• public/media/nova-ui/fluxo-padrao-preenchido.png

10. Scripts validados

node scripts/sagaz-flowdefault-mapear.mjs        # lista de canais
node scripts/sagaz-flowdefault-canal.mjs         # config (4 tipos)
node scripts/sagaz-flowdefault-locator.mjs       # Salvar com locator (scroll automatico)
node scripts/sagaz-flowdefault-reverter.mjs      # Clear X + Salvar (revert)