Runbook — Assistente Interno do Sagazchat

Manual operacional pra entender e configurar o Assistente Interno (orb roxo flutuante) — GPT embutido pra ajudar atendente/usuário durante o uso da plataforma.

Status: validado live em 2026-08-30, app v4.24.1. O assistente já está atribuído ao administrador (Assistente Exemplo).

1. O que é

O Assistente Interno é um chatbot de IA acoplado ao operador, não ao cliente final. Aparece como um orb roxo animado (vídeo MP4) flutuando no canto inferior direito de todas as telas do app.

Diferente de Assistentes IA (/manager-ia) que respondem clientes externos no WhatsApp/Instagram, este é pra ajudar o vendedor/atendente humano: tirar dúvidas durante o atendimento, consultar informações, simular respostas. É como ter o ChatGPT dentro da plataforma.

2. Onde fica

2.1 Tela de configuração

• Sidebar: Criação > IA > Assistente Interno (item dentro do grupo expansível “IA”)
• Rota: https://app.sagazchat.com/internal-assistant
• Heading: “Assistente Interno”
• Descrição na tela: “Atribua um assistente de IA a cada usuário da empresa. O assistente fica disponível como um chat flutuante dentro do sistema.”

Sidebar grupo “IA” (descoberto nesta auditoria): contém 3 itens em sequência: Assistentes IA (/manager-ia), Assistente Interno (/internal-assistant), Prompts (/prompts/general). O grupo IA fica em Criação, abaixo de Kanban’s.

2.2 Orb flutuante (interface de uso)

• Aparece em todas as telas do app (canto inferior direito).
• DOM: <video> element com classe vazia em position: fixed, ~(1476, 875), tamanho 111×114.
• O orb tem animação MP4 contínua.
• Click → abre painel lateral inline (não modal) à direita, com cabeçalho “Assistente Exemplo” e botão “Nova conversa”.

3. Tela /internal-assistant

3.1 Layout

Elemento	Descrição
Heading	”Assistente Interno” com ícone do orb roxo
Descrição	”Atribua um assistente de IA a cada usuário da empresa. O assistente fica disponível como um chat flutuante dentro do sistema.”
Busca	input[placeholder="Buscar por nome ou email"]
Tabela	Colunas Nome / Email / Assistente atribuído
Combobox por linha	Permite escolher um ou mais Assistentes IA disponíveis pra aquele usuário

3.2 Tabela observada na conta exemplo

Nome	Email	Assistente atribuído
Fulano Exemplo	admin@exemplo.com	Assistente Exemplo

3.3 Endpoints validados

• GET /internal-assistant/me/can-configure — verifica permissão de configuração
• GET /internal-assistant/users — lista usuários da empresa
• GET /assistents — lista Assistentes IA disponíveis
• GET /internal-assistant/me/assistants — assistentes atribuídos ao usuário corrente
• PUT /users/{userId}/internal-assistants — atribui/substitui múltiplos assistentes; body {assistentIaIds:[...]}
• GET /internal-assistant/threads — lista threads do usuário corrente
• POST /internal-assistant/threads — cria thread
• DELETE /internal-assistant/threads/{threadId} — remove thread

Endpoints confirmados no bundle do app v4.24.1 (live 2026-08-30). Não usar /internal-assistant/me/config, PUT /internal-assistant/users/{userId} ou POST /internal-assistant/assign.

4. Painel do orb (interface de uso)

4.1 Estado inicial

• Cabeçalho: “Assistente Exemplo” + ícones + (nova conversa?), minimizar ─, fechar ×; botão global Abrir chat de assistentes reabre o painel
• Corpo: ícone grande do orb + “Como posso ajudar hoje?” + “Comece uma nova conversa pra perguntar qualquer coisa.”
• Botão verde “Nova conversa” centralizado

4.2 Dimensões e posicionamento

• Painel inline (não modal — [role="dialog"] não é setado)
• Position fixed, (1156, 284), tamanho 420×620
• Ancora ao canto inferior direito, expande pra cima/esquerda

4.3 Conversas

Quando o usuário clica em “Nova conversa”:

• POST /internal-assistant/threads cria um thread
• Mensagens são trocadas via stream/API
  • Histórico fica salvo em GET /internal-assistant/threads; exclusão usa DELETE /internal-assistant/threads/{threadId}

Fluxo de chat real (digitar pergunta, receber resposta) não foi exercitado nesta auditoria pra não consumir tokens da conta.

5. Ações seguras vs disparadoras (pra IA)

Seguras:

• GET /internal-assistant/me/can-configure
• GET /internal-assistant/users
• GET /internal-assistant/threads
• Abrir orb e fechar (X ou minimizar)
• Abrir tela /internal-assistant e visualizar a tabela

Disparadoras (consomem tokens reais):

• Clicar Nova conversa + enviar mensagem
• Alterar Assistentes atribuídos de um usuário (mudança imediata via combobox e PUT /users/{userId}/internal-assistants)

6. Distinção entre os 3 tipos de “Assistente” do Sagazchat

Recurso	Quem fala	Onde aparece	Pra que serve
Assistentes IA (/manager-ia)	IA com cliente externo	Chat ao vivo (WhatsApp etc)	Responder o cliente automaticamente
Assistente Interno (/internal-assistant)	IA com operador interno	Orb flutuante no app	Ajudar atendente/vendedor durante o uso
Prompts (/prompts/general)	(— ainda não auditado)	(— a validar)	(— a validar)

Mesmo motor (GPT/OpenAI provavelmente), interfaces e propósitos diferentes.

7. Quirks

• Orb é <video>, não <button> — seletor por tag se for fazer click programático
• Posição fixa do orb (~1476, 875) colide visualmente com o seletor de idioma (Português/English) em ~1531, 981 — fácil errar coord
• Painel do orb não é [role="dialog"] — é div flutuante, fechar via X (não Escape, geralmente)
• “Assistente Exemplo” é o nome default do assistente atribuído na conta auditada — provável que seja criado automaticamente quando empresa é provisionada
• Sidebar tem grupo “IA” com 3 itens — não tinha mapeado antes desta auditoria

8. Pendências

• Fluxo completo de chat (Nova conversa → mensagem → resposta) — contrato do endpoint de streaming ainda não documentado
• Como o assistente acessa dados do atendimento atual (vê a conversa do cliente? só responde genericamente?)
• Permissões detalhadas além de can-configure (admin vs user) — ainda não documentadas
• Tela “Prompts” (/prompts/general) — escopo compartilhado de prompts ainda não confirmado
• Como o orb se comporta em telas modais (sobrepõe? some?)

9. Snippets Playwright

9.1 Abrir tela de config

await page.goto('https://app.sagazchat.com/internal-assistant', { waitUntil: 'domcontentloaded' });
// captura: GET /internal-assistant/me/can-configure, GET /internal-assistant/users

9.2 Clicar no orb

const orb = await page.evaluate(() => {
  const v = Array.from(document.querySelectorAll('video')).find((el) => {
    const r = el.getBoundingClientRect();
    return r.x > 1200 && r.y > 700;
  });
  if (!v) return null;
  const r = v.getBoundingClientRect();
  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
});
await page.mouse.click(orb.x, orb.y);
await page.waitForTimeout(2000);
// painel inline abre — GET /internal-assistant/threads

10. Scripts criados

• scripts/sagaz-interno-investigar.mjs — tela /internal-assistant + sidebar item
• scripts/sagaz-interno-orb.mjs — click no orb e captura do painel inline