Spec: confirmação de agenda via WhatsApp (Klingo Telefonia)
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Gustavo
co-authored by
Claude Sonnet 5
Claude Sonnet 5
parent
637951d6e2
commit
96bdb02a08
@@ -0,0 +1,176 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user