Runbook - Respostas Rápidas do Sagazchat

Manual operacional para gerenciar Configurações > Respostas Rápidas no Sagazchat. Respostas rapidas sao atalhos (/atalho) que o atendente dispara na conversa para enviar mensagens pre-formatadas — texto, audio, imagem, video, arquivo ou sticker.

Status: validado em 2026-05-11 na conta exemplo. Criado e excluido lab-teste (id=229, type=text) para mapeamento.

1. Onde fica

• Sidebar: Configurações > Respostas Rápidas
• URL: https://app.sagazchat.com/quick-messages
• Endpoint backend: /quick-messages (mesma nomenclatura da rota UI).

2. Estrutura da lista

A tela /quick-messages mostra:

• breadcrumb Painel de controle > Respostas rápidas;
• botao Nova Resposta (canto superior direito);
• abas de filtro por tipo: Todos / Textos / Arquivos / Aúdios / Imagens / Vídeos / Stickers;
• busca por atalho;
• tabela com colunas Atalho, Mensagem (preview), Compartilhado (Ativo/Inativo);
• kebab ⋮ em cada linha.

3. Criar resposta rapida

3.1 Passo a passo via UI

1. Clicar Nova Resposta.

2. Modal Mensagem Rápida abre com:

   • secao Defina o Atalho + input Atalho (name=shortcode);
   • secao Selecione o tipo com 6 botoes: Texto / Áudio / Imagem / Vídeo / Arquivo / Sticker;
   • botoes Cancelar / Salvar.

   

3. Preencher o atalho (sem espacos, ex: lab-teste).

4. Clicar no botao do tipo desejado. Quando clica em Texto, abre textarea[name="message"] para o texto:

   

5. Para tipos com midia (Audio, Imagem, Video, Arquivo, Sticker), abre o seletor de arquivo (a confirmar comportamento exato — nao testado nesta sessao).

6. Clicar Salvar.

   

3.2 Endpoint

POST https://backend.sagazchat.com/quick-messages
Authorization: Bearer <jwt>
Content-Type: multipart/form-data

IMPORTANTE: a requisicao usa multipart/form-data, nao JSON. Provavelmente para suportar upload de arquivo nos tipos midia.

Form fields validados (criando tipo Texto):

Campo	Valor (exemplo)
type	text (ou audio, image, video, file, sticker)
shortcode	lab-teste
message	LAB TESTE - resposta rapida de teste
recordNow	true

Resposta validada:

{
  "id": 229,
  "shortcode": "lab-teste",
  "message": "LAB TESTE - resposta rapida de teste",
  "companyId": 39,
  "userId": 39,
  "type": "text",
  "url": null,
  "originalName": null,
  "recordNow": true,
  "shared": false,
  "createdAt": "2026-05-11T15:59:05.129Z",
  "updatedAt": "2026-05-11T15:59:05.129Z"
}

3.3 Quirks do payload

• multipart/form-data mesmo no tipo Texto — frontend usa o mesmo content-type para todos os tipos por uniformidade.
• recordNow: true — significado nao clarificado. Provavelmente flag de gravacao on-the-fly para audio.
• url / originalName ficam null no tipo Texto. Para midia, sao populados com o path no servidor + nome original do arquivo.

3.4 Regras de conteudo (confirmadas pelo administrador 2026-05-11)

• Cada resposta tem UM tipo so — Texto OU Audio OU Imagem OU Video OU Arquivo OU Sticker. Nao da pra combinar texto+imagem no mesmo atalho. Se precisar “imagem com legenda”, criar dois atalhos ou usar Fluxo.
• Em Texto, e literalmente texto — nao ha interpolacao de variaveis. Escrever {nome} ou {cliente.email} envia o caractere literal, nao o valor da variavel. Para mensagens dinamicas, usar Fluxo (que tem blocos com variaveis).
• Em tipos midia, o conteudo e o arquivo carregado — sem campo de texto adicional. O message no payload fica vazio.

4. Listagem

GET https://backend.sagazchat.com/quick-messages/list?companyId=39&userId=39

Resposta: array de respostas. Cada item inclui ainda company.id e company.name (join). Exemplo real:

[
  { "id": 229, "shortcode": "lab-teste", "type": "text", "url": null, "shared": false, ... },
  { "id": 184, "shortcode": "Teste",     "type": "image", "url": "quickc39d1776131119612.png", "originalName": "1000184935.png", "shared": false, ... }
]

5. Editar resposta

Kebab ⋮ da linha > Editar. Abre o mesmo modal Mensagem Rápida com os campos populados.

Comportamento detalhado de upload em Editar nao foi testado nesta sessao.

6. Compartilhar (toggle)

Kebab ⋮ da linha > Compartilhar. Acao instantanea, nao abre dialog.

• Estado inicial: Inativo (shared: false).
• Apos clicar: Ativo (shared: true).

Significado: quando shared: true, a resposta rapida fica disponivel para todos os usuarios da conta. Quando false, e privada do criador (campo userId).

Endpoint exato do toggle nao foi capturado (regex inicial nao pegou). Provavelmente PUT /quick-messages/{id}/share ou PATCH /quick-messages/{id}. [a validar]

7. Excluir

Kebab ⋮ > Excluir.

Modal de confirmacao:

• Titulo: Excluir Atalho {nome}?
• Texto: “Deseja realmente excluir este atalho?”
• Botoes: Cancelar / Deletar

DELETE https://backend.sagazchat.com/quick-messages/{id}
→ 200 { "message": "Contact deleted" }

Quirk: resposta diz Contact deleted (typo do backend — deveria ser Quick message deleted ou similar). Provavelmente reuso de codigo do modulo Contatos.

8. Usar no atendimento

No Bate Papo ao vivo, o atendente digita /<atalho> para disparar a resposta:

• Digitar /lab-teste aciona a resposta cadastrada com aquele shortcode.
• O preview da mensagem aparece e e enviada ao confirmar.

Filtros por tipo (Todos/Textos/Arquivos/Aúdios/Imagens/Vídeos/Stickers) ajudam a navegar quando a lista cresce.

9. Acoes seguras e perigosas

Acao	Impacto	Regra
Abrir lista	Leitura	Seguro.
Buscar/filtrar	Leitura	Seguro.
Criar lab-*	POST /quick-messages	OK para teste com cleanup.
Editar resposta real	Altera resposta usada por atendentes	Nao fazer sem ordem.
Toggle Compartilhar	Muda escopo (pessoal ↔ todos os atendentes)	Confirmar antes; pode expor texto pessoal.
Excluir resposta com uso	Quebra atalho que atendentes usam	Nao fazer sem ordem.

10. Quirks consolidados

• multipart/form-data em todos os tipos (mesmo Texto sem midia).
• recordNow: true padrao — significado a confirmar.
• Compartilhar e toggle direto (Inativo↔Ativo), sem modal.
• Modal Excluir diz “Deletar” (botao), nao “Excluir”.
• Resposta DELETE retorna "Contact deleted" — typo do backend.
• Listagem usa /list?companyId=&userId= com query params (nao path).
• Ha 2 textareas no DOM quando tipo Texto: a real (name="message") e um shadow MUI invisivel (aria-hidden, readonly). Usar .last() pega o errado — preferir textarea[name="message"].

11. Imagens

• public/media/nova-ui/respostas-rapidas-lista.png
• public/media/nova-ui/respostas-rapidas-modal-add.png
• public/media/nova-ui/respostas-rapidas-modal-tipo-texto.png
• public/media/nova-ui/respostas-rapidas-modal-preenchido.png
• public/media/nova-ui/respostas-rapidas-compartilhado-ativo.png
• public/media/nova-ui/respostas-rapidas-modal-excluir.png

12. Pendencias

• Testar upload real (Imagem, Audio, Video, Arquivo, Sticker) e capturar payload.
• Validar endpoint exato do toggle Compartilhar + escopo (todos da empresa ou so departamento).
• Confirmar significado de recordNow: true.
• Confirmar uso real do atalho /<atalho> no Bate Papo.
• Capturar PUT/PATCH de Editar.

13. Scripts validados

node scripts/sagaz-respostas-mapear.mjs        # lista
node scripts/sagaz-respostas-inspect.mjs       # modal Nova Resposta + kebab
node scripts/sagaz-respostas-continuar.mjs     # cria lab-teste + payload POST
node scripts/sagaz-respostas-cleanup.mjs       # toggle Compartilhar (silente) + DELETE