Guia de configuração manual

Guia de Configuração Manual — Respond.io (Luana 3.0)

Este documento descreve tudo que precisa ser configurado manualmente no painel do Respond.io, fora do código. A parte técnica (edge functions, KBs, tools HTTP, webhooks) já está entregue nas Fases 1 e 2 do plano.

Ordem recomendada de execução: Contact Fields → Tags → Lifecycle Stages → AI Agents → Workflows. Faça primeiro no canal MG (489695) como piloto; só replique pro SP (480178) depois de 48h estável.

0. Pré-requisitos

1. Contact Fields (23 campos)

Settings → Contact Fields → Add Field.

# Nome interno Label Tipo Observação
1 cpf CPF Text 11 dígitos, sem pontuação
2 nome_completo Nome completo Text —
3 data_nascimento Data nascimento Date DD/MM/AAAA
4 cidade_paciente Cidade Text usada pelo Receptionist
5 estado_paciente UF Text 2 letras
6 canal_origem Canal de origem Text 489695/480178/etc
7 unidade_preferida_id Unidade preferida (UUID) Text —
8 proximo_agendamento_id Próx. agendamento (UUID) Text populado por webhook
9 proximo_agendamento_data Próx. agendamento data Date —
10 proximo_agendamento_servico Próx. agendamento serviço Text —
11 proximo_agendamento_unidade Próx. agendamento unidade Text —
12 proximo_agendamento_medico Próx. agendamento médico Text —
13 proximo_agendamento_status Status próx. agendamento Text confirmado/pendente/cancelado
14 proximo_agendamento_pagamento Pagamento próx. agendamento Text pago/pendente
15 proximo_agendamento_confirmacao Confirmação próx. agendamento Text sim/nao/null
16 laudo_disponivel Laudo disponível Text sim/nao
17 laudo_link_recente Link laudo recente Text URL portal
18 laudo_data_recente Data laudo recente Date —
19 nf_disponivel NF disponível Text sim/nao
20 nf_numero Número NF Text —
21 nf_status Status NF Text emitida/pendente/erro
22 nf_link Link NF Text PDF
23 nf_data_emissao Data emissão NF Date —

⚠️ Os nomes internos devem ser exatamente esses (snake_case), porque os webhooks respond-io-webhook-* já populam por esses keys via customFields.

2. Tags (~30 tags)

Settings → Tags → Add Tag. Use prefixo id: quando a tag dispara automações (memory respond-io/automated-tagging-logic).

Tags de fluxo (workflow router)

Tags de saída (Luana → handoff)

Tags de IA (roteamento entre os 5 agents)

Veja KB_TAGS_SAIDA.md e KB_FECHAMENTO_CADENCIA.md para a semântica completa.

3. Lifecycle Stages (5 estágios)

Settings → Lifecycle Stages → ordem importa.

Etapas do ciclo de vida (configuração real em produção)

Ordem Stage Ícone Descrição Entrada automática
1 Lead 😊 Primeiro contato, ainda não foi ofertado horário. Default ao criar contato (Conversation Opened).
2 Ofertado horário 📅 Luana já enviou opções de horário, aguardando escolha. Tool respond-io-horarios executada com sucesso.
3 Agendado ✅ Tem agendamento confirmado no Supabase. Webhook respond-io-webhook-agendamento (trigger SQL em agendamentos INSERT).
4 Em Atendimento 😊 Compareceu ou está em consulta hoje. Cron diário W7 às 00:00 (move agendamentos do dia).
5 Inativo ❤️ Sem interação 180+ dias e sem agendamento futuro. Cron mensal W7.
6 Pós-Consulta (Venda Fechada) 😎 Atendimento concluído, aguardando avaliação/laudo/NF. Webhook quando status = compareceu.

Etapas de perda

Stage Ícone Quando usar
Deseja convênio apenas 🧊 Paciente recusa atendimento particular (Luana detecta menção a "convênio/plano" + recusa). Tag RecusouAgendar + id:convenio-apenas.
Não quis oferta ❌ Paciente recusou o slot oferecido sem pedir reagendamento. Tag RecusouAgendar.

Importante: Respond.io só permite setar Lifecycle Stage via Workflow Step "Update Lifecycle Stage", não direto via API REST. Por isso o webhook envia uma tag id:* e o Workflow correspondente faz a mudança de stage.

4. AI Agents (5 IAs)

Settings → AI Agents → Create Agent. Para cada um:

  1. Model: gpt-4o (ou claude-3.5-sonnet se preferir).
  2. Temperature: 0.3 (financeiro/laudo) ou 0.5 (receptionist/pré/pós).
  3. System Prompt: colar conteúdo de src/content/respondio/INSTRUCOES_LUANA_*.md correspondente.
  4. Knowledge Source: URL única → https://kb-respondio.clinicasinstitutosaude.com.br/ (página índice). O crawler indexa as 16 KBs automaticamente.
  5. Tools: habilitar as edge functions abaixo via "Add Custom Tool" (config detalhada em docs/RESPOND_IO_AGENTE_HTTP.md).

4.1 Receptionist (MG e SP — agent por canal)

4.2 Pré-Consulta

4.3 Pós-Consulta

4.4 Financeiro

4.5 Laudo

5. Workflows (8 workflows)

Workflows → New Workflow.

W1 — Router de Entrada

W2 — Cadência (sem resposta)

W3 — Webhook Agendamento Criado

W4 — Webhook Consulta Finalizada

W5 — Webhook Cancelamento

W6 — Webhook Avaliação (NPS)

W7 — Cron Diário (00:00)

W8 — Bridge (KB fallback)

6. Templates Meta (aprovação prévia obrigatória)

Submeter no Meta Business Manager → WhatsApp → Templates:

Nome Categoria Idioma Uso
cobranca_2h UTILITY pt_BR Lembrete 2h antes
cobranca_6h UTILITY pt_BR Confirmação 6h antes
cobranca_18h UTILITY pt_BR Pré-confirmação noite anterior
pendencias_dados_nf UTILITY pt_BR Coletar dados pendentes (memory existente)
reagendamento_tentativa UTILITY pt_BR Oferecer novo slot
avaliacao_nps MARKETING pt_BR Link NPS pós-consulta

Regras de sanitização: sem \t, \n duplicado, ou caracteres invisíveis (memory whatsapp-template-sanitization-rules).

7. Triggers SQL (pg_net → webhooks Respond.io)

Criados no Supabase (não no Respond.io), mas listados aqui para visibilidade. Pendente — Fase 3.

-- pseudo, ainda não aplicado
CREATE TRIGGER trg_agendamento_to_respondio
AFTER INSERT OR UPDATE OF status ON agendamentos
FOR EACH ROW EXECUTE FUNCTION call_respond_io_webhook();

Funções alvo: respond-io-webhook-agendamento, respond-io-webhook-laudo, respond-io-webhook-nf.

8. Checklist final de go-live (canal MG primeiro)

9. Rollback rápido

Se algo quebrar em produção:

  1. AI Agent alucinou: vá em /admin/respond-io/prompt-versions, ative versão anterior.
  2. Tool retornando erro: desative a tool no agent (Settings → Tools → toggle off); Luana volta a usar só KB.
  3. Workflow disparando demais: Workflows → toggle off no W problemático.
  4. KB indexação errada: ative kb_active_version apontando para snapshot vYYYYMMDD antigo.

Documento vivo. Atualize ao adicionar novos Contact Fields, Tags ou Workflows.