177 lines
9.2 KiB
Markdown
177 lines
9.2 KiB
Markdown
# Design — Confirmação de Agenda via WhatsApp (Klingo Telefonia)
|
|
|
|
**Data:** 2026-08-11
|
|
**Status:** Aprovado pelo usuário, aguardando plano de implementação.
|
|
|
|
## Objetivo
|
|
|
|
Permitir que o paciente confirme presença numa consulta agendada via
|
|
WhatsApp, usando a **Klingo Telefonia API**
|
|
(`https://api-externa.klingo.app/api/telefonia`, auth `X-APP-TOKEN`) —
|
|
uma API separada da API de agendamento do Klingo já integrada
|
|
anteriormente. Dois fluxos compõem a feature: um **lembrete proativo**
|
|
(cron diário avisando o paciente da consulta do dia seguinte) e uma
|
|
**confirmação reativa** (o paciente responde "sim"/"não" no WhatsApp, e
|
|
o sistema registra isso no Klingo).
|
|
|
|
## Relação com o trabalho anterior
|
|
|
|
- Reaproveita o **MCP Server standalone de Mensageria (Z-PRO)**
|
|
(`docs/n8n-agendamento-runbook.md`, seção 17) para o disparo do
|
|
lembrete — este design não cria nenhuma lógica nova de envio de
|
|
mensagem, só consome a tool `enviar_texto` já validada.
|
|
- É um MCP **novo e separado** do MCP de agendamento do Klingo
|
|
(`docs/n8n-agendamento-runbook.md`, seção 14.1) — API diferente
|
|
(Telefonia vs. Agendamento), auth diferente (`X-APP-TOKEN` vs. o que
|
|
for usado no de agendamento), propósito diferente. Mesma disciplina
|
|
de não misturar integrações já estabelecida no projeto.
|
|
- Escopo excludente confirmado pelo usuário: o endpoint `POST /entrada`
|
|
da API de Telefonia (registro de chamada telefônica) fica **fora**
|
|
desta feature — "não envolve telefonia, apenas a confirmação no
|
|
nosso sistema de WhatsApp".
|
|
|
|
## Escopo: 6 tools do MCP Server "Klingo Telefonia"
|
|
|
|
| Tool | Endpoint | Uso |
|
|
| --- | --- | --- |
|
|
| `listar_agendamentos_do_dia` | `GET /lista/{data}` | Base do lembrete proativo — todas as consultas de uma data |
|
|
| `consultar_agendamento_por_id` | `GET /{id}` | Detalhe de uma consulta específica |
|
|
| `buscar_agendamento_pendente_por_cpf` | `GET /lista_ultimo_por_cpf` | O agente usa isso pra achar qual consulta o paciente está confirmando, a partir do CPF/telefone dele |
|
|
| `confirmar_presenca` | `POST /confirmar` | Ação central — registra a confirmação/recusa de presença no Klingo |
|
|
| `registrar_nps` | `POST /nps` | Pesquisa de satisfação pós-consulta — fora do fluxo de confirmação em si, mas dentro do escopo "tudo" aprovado pelo usuário |
|
|
| `consultar_bloqueios` | `GET /bloqueios` | Consulta de bloqueios de agenda — informativo |
|
|
|
|
`POST /entrada` excluído (ver seção anterior).
|
|
|
|
## Arquitetura
|
|
|
|
Três peças distintas, cada uma um conjunto de workflows n8n:
|
|
|
|
```
|
|
1) MCP Server "Klingo Telefonia" (servidor + 6 sub-workflows)
|
|
[MCP Server Trigger] ──Tools──┬── listar_agendamentos_do_dia ──▶ GET /lista/{data}
|
|
├── consultar_agendamento_por_id ──▶ GET /{id}
|
|
├── buscar_agendamento_pendente_por_cpf ──▶ GET /lista_ultimo_por_cpf
|
|
├── confirmar_presenca ──▶ POST /confirmar
|
|
├── registrar_nps ──▶ POST /nps
|
|
└── consultar_bloqueios ──▶ GET /bloqueios
|
|
|
|
2) Workflow proativo "Lembrete de Confirmação — Klingo (exemplo)"
|
|
[Cron 8h diário] → [Klingo Telefonia: listar_agendamentos_do_dia (amanhã)]
|
|
→ [Loop por agendamento] → [Mensageria ZPRO: enviar_texto]
|
|
|
|
3) Workflow de exemplo "Confirmação de Agenda — GChat - Klingo+Z-PRO (exemplo)"
|
|
[Webhook Z-PRO/GChat] → [AI Agent] → resposta ao paciente
|
|
tools: MCP Klingo Telefonia (buscar_agendamento_pendente_por_cpf, confirmar_presenca)
|
|
memória: Postgres Chat Memory (mesmo padrão da clínica exemplo)
|
|
```
|
|
|
|
Nenhuma das três peças depende de cliente real Klingo em produção para
|
|
existir estruturalmente — mesma disciplina já usada pra Klingo/SysLife/
|
|
ClinicAll no agendamento: construir e validar a estrutura
|
|
(`n8n_validate_workflow`, 0 erros), sem teste de ponta a ponta contra a
|
|
API real (sem credencial de teste disponível no momento).
|
|
|
|
## Componentes
|
|
|
|
### MCP Server "Klingo Telefonia"
|
|
|
|
Mesmo esqueleto de sub-workflow usado em todos os outros MCP Servers
|
|
deste projeto: `Execute Workflow Trigger` → `Config Klingo Telefonia`
|
|
(`Set` com `baseUrl` e placeholder de auth) → montagem de
|
|
query/params/body → `HTTP Request` (header `X-APP-TOKEN`,
|
|
`neverError: true` + `fullResponse: true`) → classificação de resultado
|
|
(taxonomia genérica já usada nos outros providers:
|
|
`AUTHENTICATION_ERROR` 401/403, `NOT_FOUND` 404, `VALIDATION_ERROR`
|
|
400/422, `KLINGO_TELEFONIA_API_ERROR` demais).
|
|
|
|
- **`listar_agendamentos_do_dia`**: parâmetro `data` (formato a
|
|
confirmar contra a spec do SwaggerHub — assumido `YYYY-MM-DD` até
|
|
verificação). Devolve lista de agendamentos do dia.
|
|
- **`consultar_agendamento_por_id`**: parâmetro `id`.
|
|
- **`buscar_agendamento_pendente_por_cpf`**: parâmetro `cpf`.
|
|
- **`confirmar_presenca`**: parâmetros `id` (ou `idAgenda`, a confirmar
|
|
contra a spec) e `resposta`/`confirmado` (a confirmar o formato exato
|
|
esperado pela API — booleano vs. enum — contra o SwaggerHub na hora
|
|
da implementação).
|
|
- **`registrar_nps`**: parâmetros `id` e nota/comentário (formato a
|
|
confirmar contra a spec).
|
|
- **`consultar_bloqueios`**: sem parâmetros obrigatórios óbvios — a
|
|
confirmar contra a spec (pode aceitar filtro de data/profissional).
|
|
|
|
**Pendência explícita**: os nomes exatos de campo de cada endpoint
|
|
(além do que já foi inspecionado) serão confirmados durante a
|
|
implementação, consultando o spec OpenAPI do SwaggerHub
|
|
(`api.swaggerhub.com/apis/agsx30/klingo-api-telefonia/1.0.0` — técnica
|
|
de acesso direto ao spec raw já validada nesta sessão). Nenhum campo
|
|
será inventado; se o spec não documentar algo necessário, fica
|
|
registrado como pendência, não como suposição.
|
|
|
|
**Autenticação**: assim como o MCP de Mensageria, nenhuma credencial é
|
|
inventada — a criação da credencial `httpHeaderAuth` com o
|
|
`X-APP-TOKEN` real fica pré-requisito manual do usuário, feito quando
|
|
houver uma clínica Klingo real pra testar.
|
|
|
|
### Workflow proativo "Lembrete de Confirmação — Klingo (exemplo)"
|
|
|
|
```
|
|
[Cron Trigger, 8h diário] → [Klingo Telefonia: listar_agendamentos_do_dia]
|
|
(data = amanhã, calculada via expressão)
|
|
→ [Split in Batches / loop] → [Mensageria ZPRO: enviar_texto]
|
|
(number = telefone do paciente, body = mensagem de lembrete com
|
|
nome do paciente + data/hora da consulta)
|
|
```
|
|
|
|
Chama diretamente as tools dos dois MCP Servers via `Execute Workflow`
|
|
(não via AI Agent — fluxo determinístico, sem necessidade de
|
|
interpretação de linguagem natural). Sem lógica de "já lembrado
|
|
antes" nesta rodada — se rodar mais de uma vez no mesmo dia por engano,
|
|
manda lembrete duplicado; ajuste futuro se isso for um problema real.
|
|
Texto do lembrete fixo nesta rodada (sem config via Google Docs — é
|
|
workflow de exemplo, sem cliente/gestor real associado ainda).
|
|
|
|
### Workflow de exemplo "Confirmação de Agenda — GChat - Klingo+Z-PRO (exemplo)"
|
|
|
|
Réplica estrutural do padrão já usado na clínica exemplo (webhook →
|
|
AI Agent → memória Postgres), mas **sem cliente real associado** —
|
|
workflow de referência/esqueleto, mesmo espírito dos MCP Servers de
|
|
agendamento Klingo/SysLife/ClinicAll já construídos sem clínica real.
|
|
|
|
- **Webhook**: mesmo contrato do Z-PRO/GChat já documentado (seção 6
|
|
do runbook).
|
|
- **AI Agent**: `systemMessage` fixo (sem Google Docs nesta rodada)
|
|
instruindo o agente a: entender se a mensagem do paciente é uma
|
|
resposta de confirmação/recusa de presença; se for, usar
|
|
`buscar_agendamento_pendente_por_cpf` pra achar a consulta pendente
|
|
(a partir do telefone/CPF do contato do webhook) e então chamar
|
|
`confirmar_presenca`; responder ao paciente confirmando o registro.
|
|
- **Tools**: MCP Klingo Telefonia — só `buscar_agendamento_pendente_por_cpf`
|
|
e `confirmar_presenca` conectados nesta rodada (as outras 4 tools do
|
|
MCP existem mas não são atribuídas a este agente específico — podem
|
|
ser usadas por outros workflows futuros).
|
|
- **Memória**: `Postgres Chat Memory`, mesmo padrão da seção 16 do
|
|
runbook — credencial própria a ser criada quando houver cliente real.
|
|
|
|
## Fora de escopo (adiado)
|
|
|
|
- `POST /entrada` (telefonia em si) — explicitamente fora, por
|
|
instrução do usuário.
|
|
- Lógica de "não lembrar de novo se já confirmado" no workflow
|
|
proativo — YAGNI até aparecer o caso real.
|
|
- Configuração via Google Docs no workflow de exemplo — sem gestor/
|
|
cliente real associado ainda; replicar quando houver.
|
|
- Teste de ponta a ponta contra a API real do Klingo Telefonia — sem
|
|
credencial de teste disponível.
|
|
- Qualquer UI/relatório de acompanhamento de confirmações — não
|
|
solicitado.
|
|
|
|
## Testes
|
|
|
|
Sem cliente/credencial real Klingo Telefonia disponível: validação
|
|
estrutural apenas (`n8n_validate_workflow`, 0 erros esperados em todos
|
|
os workflows) — mesma disciplina já usada para Klingo/SysLife/ClinicAll
|
|
no agendamento. Teste real de ponta a ponta (lembrete disparando,
|
|
paciente respondendo, `/confirmar` sendo chamado corretamente) fica
|
|
pendente para quando houver uma clínica Klingo real em produção, com
|
|
credencial de teste da API de Telefonia.
|