@lionchat/mcp-server 1.10.0 → 1.10.1

package/dist/docs/resources/conversation-flows.md

@@ -420,6 +420,154 @@ POST /api/v1/accounts/{account_id}/automation_rules
   "event_name": "conversation_updated",
   "action_types": ["label_added"],
   "conditions": [{"attribute_key": "labels", "filter_operator": "contains", "values": ["vip"]}],
-  "actions": [{"action_name": "send_email_to_team", "action_params": {"team_ids": [1], "message": "VIP!"}}]
+  "actions": [{"action_name": "send_email_to_team", "action_params": [{"team_ids": [1], "message": "VIP!"}]}]
 }
 ```
+
+---
+
+## Condicoes de automacao — e a REGRA DO CONECTOR
+
+```json
+"conditions": [
+  {"attribute_key": "status",  "filter_operator": "equal_to", "values": ["resolved"], "query_operator": "AND"},
+  {"attribute_key": "labels",  "filter_operator": "equal_to", "values": ["vip"],      "query_operator": null}
+]
+```
+
+### O conector (`query_operator`) — leia isto antes de gravar
+
+O conector **liga a condicao com a SEGUINTE**. Logo:
+
+- A **ULTIMA** condicao **TEM** que ter `query_operator: null`.
+- Condicao **UNICA** = `query_operator: null` (nao ha proxima pra ligar).
+- Valores aceitos nas demais: `"AND"` ou `"OR"`.
+
+> **A API valida o VALOR do conector, mas NAO a POSICAO.** Conector na ultima condicao **salva com
+> sucesso**, aparece certo na tela — e a regra nunca dispara.
+>
+> Incidente real: **8 regras criadas pelo conector de IA entre 26 e 30/07/2026, em 3 contas
+> diferentes, todas com conector na ultima condicao. Todas nasceram mortas.** A pergunta ao banco
+> saia pela metade (`... IN ($1) and`), o erro era engolido e a regra respondia "nada casou". A conta
+> 62 ficou com as **6** regras de etiquetagem automatica paradas. Medido em producao em 03/08:
+> **732 erros por hora**.
+>
+> O motor foi corrigido em 03/08 (a limpeza acontece ao montar a consulta), entao regra torta nao
+> quebra mais. **Mas continue gravando certo:** a tela de edicao le o dado cru e formato errado
+> aparece estranho ali — mesmo efeito do campo de template que sumia da tela.
+
+### Campos da condicao
+
+| Campo | Obrigatorio | O que e |
+|---|---|---|
+| `attribute_key` | SIM | Campo padrao (ver abaixo) ou a chave de um atributo personalizado que **exista na conta** |
+| `filter_operator` | SIM | Como comparar |
+| `values` | SIM (menos em `is_present`/`is_not_present`) | Array, sempre |
+| `query_operator` | SIM em todas | `"AND"`/`"OR"`; **`null` na ultima** |
+| `custom_attribute_type` | so p/ atributo personalizado | `conversation_attribute` ou `contact_attribute` |
+
+### Operadores de filtro
+
+`equal_to`, `not_equal_to`, `contains`, `does_not_contain`, `is_present`, `is_not_present`,
+`is_greater_than`, `is_less_than`, `starts_with`, `days_before`, `days_ago`, `last_days`, `today`,
+`yesterday`.
+
+**Cada campo aceita so um subconjunto.** Operador que o campo nao aceita faz a regra inteira falhar
+na validacao. Na duvida, leia uma regra que ja funciona com `lionchat_automation_rules_show` e copie.
+
+### Chave que a conta nao conhece
+
+Se `attribute_key` nao for um campo padrao **nem** um atributo personalizado existente na conta, a
+regra **inteira** falha na validacao e nunca dispara — erro
+`Automation conditions <chave> not supported`. Aconteceu de verdade na conta 62 (`tipo_interesse`).
+Antes de usar atributo personalizado numa condicao, confirme que ele existe com
+`lionchat_custom_attributes_list`.
+
+---
+
+## Acoes de automacao — formato do `action_params`
+
+> **REGRA DE OURO:** `action_params` e SEMPRE um **array**, mesmo quando so tem um item.
+> O backend le `params[0]`. Passar um objeto solto (`{...}` em vez de `[{...}]`) quebra a acao.
+
+> **PERIGO — falha silenciosa:** o `action_params` e um campo livre (JSONB). A API **aceita e grava
+> qualquer formato**, sem validar. Se as chaves estiverem erradas, a regra e salva com sucesso, o
+> painel mostra a acao na tela, e na hora de disparar ela **nao faz nada e nao registra erro nenhum**
+> — sem log, sem mensagem falhada, sem aviso. Por isso: **nunca invente nome de chave**. Se a acao
+> nao estiver documentada abaixo, leia uma regra existente com `lionchat_automation_rules_show` e
+> copie o formato exato dela.
+>
+> Incidente real (conta 39, 02-03/08/2026): uma IA gravou `template_name`/`template_id` em vez de
+> `name`/`id`. A regra ficou 14 horas sem enviar nada, 9 leads pagos entraram e ninguem foi avisado.
+
+### `send_whatsapp_template` — ATENCAO ESPECIAL
+
+Envia um modelo aprovado da Meta. **So funciona em caixa WhatsApp API Oficial (Cloud).**
+
+```json
+{
+  "action_name": "send_whatsapp_template",
+  "action_params": [{
+    "name": "confirmacao_pedido",
+    "id": "1071396275361941",
+    "language": "pt_BR",
+    "category": "UTILITY",
+    "processed_params": {"body": {"1": "{{contact.first_name}}"}}
+  }]
+}
+```
+
+| Chave | Obrigatoria | O que e |
+|---|---|---|
+| `name` | **SIM** | Nome EXATO do modelo aprovado na Meta. E por ele que o envio acontece |
+| `id` | nao | ID do modelo na Meta. Serve so de reserva se `name` faltar |
+| `language` | nao (padrao `pt_BR`) | Precisa bater com o idioma do modelo aprovado |
+| `category` | nao | `UTILITY`, `MARKETING` ou `AUTHENTICATION` |
+| `processed_params` | nao | Valores das variaveis: `{"body": {"1": "...", "2": "..."}}`. Aceita Liquid (`{{contact.first_name}}`) |
+
+**NUNCA use `template_name`, `template_id`, `template_category` nem `template_language` aqui.**
+Esse e o formato dos **nos do FlowBuilder**, que e outra coisa. Na automacao, essas chaves sao
+ignoradas e a acao vira um nada silencioso.
+
+Antes de gravar, confirme que o modelo existe e esta aprovado com
+`lionchat_inboxes_whatsapp_templates_list` — o envio so acha o modelo se `name` + `language`
+casarem e o status for `approved`.
+
+### Demais acoes
+
+Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_service.rb` e
+`app/services/automation_rules/action_service.rb`.
+
+| `action_name` | `action_params` |
+|---|---|
+| `send_message` | `["texto da mensagem"]` |
+| `add_private_note` | `["nota interna"]` |
+| `send_canned_response` | `[12]` — id da resposta pronta |
+| `add_label` / `remove_label` | `["etiqueta1", "etiqueta2"]` |
+| `assign_agent` | `[70]` — o agente precisa ser membro da caixa. `["nil"]` desatribui |
+| `assign_team` | `[3]`. `["nil"]` desatribui |
+| `assign_captain_assistant` | `[17]` ou `[{"assistant_id": 17, "proactive": true}]` — `proactive` false = a IA assume mas nao fala na hora |
+| `send_email_to_team` | `[{"team_ids": [1], "message": "texto"}]` |
+| `send_webhook_event` | `["https://..."]` |
+| `send_attachment` | `[blob_ids]` — so funciona se a regra ja tiver arquivo anexado; nao da pra montar so por API |
+| `change_status` | `["resolved"]`, `["open"]`, `["pending"]` ou `["snoozed"]` |
+| `change_priority` | `["urgent"]`, `["high"]`, `["medium"]`, `["low"]`. `["nil"]` limpa |
+| `send_email_transcript` | `["a@b.com,c@d.com"]` — UMA string, varios e-mails separados por virgula |
+| `mute_conversation` | `[]` |
+| `snooze_conversation` | `[]` |
+| `resolve_conversation` / `open_conversation` / `pending_conversation` | `[]` |
+| `update_contact_attribute` / `update_conversation_attribute` | `[{"attribute_key": "chave", "value": "texto ou {{contact.phone_number}}"}]` |
+| `create_kanban_item` | `[{"funnel_id": 31, "funnel_stage": "prospeccao", "allow_duplicates": false}]` |
+| `move_kanban_item_to_stage` | `[{"funnel_id": 31, "funnel_stage": "qualificacao"}]` |
+| `assign_agent_to_kanban_item` | `[{"funnel_id": 31, "agent_id": 70, "mode": "add"}]` — `mode` aceita `add` (padrao) ou `remove_all` |
+| `add_note_to_kanban_item` | `[{"funnel_id": 31, "text": "texto da nota"}]` — a chave e **`text`**, nao `note` |
+| `set_kanban_item_status` | `[{"funnel_id": 31, "status": "won"}]` — `won`, `lost` ou `open`. Status fora disso e ignorado |
+| `start_kanban_item_timer` / `stop_kanban_item_timer` | `[{"funnel_id": 31}]` |
+
+**Acoes de Kanban:** todas precisam que a conversa ja tenha um card no funil informado. Sem card,
+a acao e pulada (fica so no log do servidor). Use `create_kanban_item` antes, na mesma regra.
+
+Lista autoritativa de nomes validos: `AutomationRule#actions_attributes` no backend. Nome de acao
+fora dessa lista e recusado com 422 ao salvar — isso a API valida. O que ela **nao** valida e o
+conteudo do `action_params`. `apply_kanban_checklist_template` existe no motor mas **nao** e uma
+acao de automacao valida (e so do FlowBuilder) — usar aqui devolve 422.

package/dist/docs/resources/data-model.md

@@ -396,11 +396,12 @@ Booking (agendamento confirmado)
 
 ## e-Clínicas (Efficient) — integração de clínicas
 
-9 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica:
+13 eventos de webhook, cada um mapeável a automação OU flow na tela Integrações > e-Clínica:
 `cliente_novo`, `agendamento_novo`, `falta`, `pagamento` (os 4 da doc oficial) +
 `agendamento_atendido`, `agendamento_alterado`, `agendamento_desmarcado`,
-`agendamento_transferido`, `cliente_baixa_pagamento` (capturados ao vivo, não documentados
-pelo e-Clínica).
+`agendamento_transferido`, `cliente_baixa_pagamento`, `cliente_alteracao`,
+`cliente_inclusao_pagamento`, `controle_laboratorio_novo`, `controle_laboratorio_alterado`
+(capturados ao vivo, não documentados pelo e-Clínica).
 
 Atributos de sistema no CONTATO (prefixo `eclinica_`, protegidos, usáveis como variável):
 

package/endpoints.json

@@ -10091,14 +10091,14 @@
         "type": "array",
         "location": "body",
         "required": true,
-        "description": "[{attribute_key, filter_operator, query_operator, values[]}]"
+        "description": "[{attribute_key, filter_operator, query_operator, values[]}] REGRA DO CONECTOR (query_operator) — LEIA ANTES DE GRAVAR: o conector liga a condicao com a SEGUINTE, logo a ULTIMA condicao TEM que ter query_operator: null (condicao UNICA tambem = null). Nas demais: 'AND' ou 'OR'. A API valida o VALOR do conector mas NAO a POSICAO — conector na ultima condicao SALVA COM SUCESSO, aparece certo na tela e a regra NUNCA dispara. Incidente real: 8 regras criadas pelo conector de IA entre 26 e 30/07/2026 em 3 contas, todas com conector na ultima condicao, todas nasceram mortas (732 erros/hora medidos em producao 03/08; a conta 62 ficou com as 6 regras de etiquetagem automatica paradas). attribute_key precisa ser campo padrao OU atributo personalizado que EXISTA na conta (senao a regra inteira falha na validacao: 'Automation conditions <chave> not supported') — conferir antes com lionchat_custom_attributes_list; atributo personalizado exige tambem custom_attribute_type ('conversation_attribute' ou 'contact_attribute'). filter_operator: equal_to, not_equal_to, contains, does_not_contain, is_present, is_not_present, is_greater_than, is_less_than, starts_with, days_before, days_ago, last_days, today, yesterday — cada campo aceita so um subconjunto. Na duvida, leia uma regra que ja funciona com lionchat_automation_rules_show e copie o formato. Detalhe no resource 'conversation-flows'."
       },
       {
         "name": "actions",
         "type": "array",
         "location": "body",
         "required": true,
-        "description": "CADA item de actions DEVE ser um OBJETO {action_name (string), action_params (array)} — NUNCA um texto/string solto. Ex.: [{\"action_name\":\"send_message\",\"action_params\":[\"Oi\"]}]. [{action_name, action_params[]}] Actions novas (2026-07-21): 'update_contact_attribute' e 'update_conversation_attribute' — action_params: [{attribute_key, value}], value aceita texto fixo OU variável Liquid (ex. {{contact.phone_number}}); grava atributo personalizado com MERGE (não apaga os demais) e passa pelo porteiro de data. 'pending_conversation' (2026-07-20, sem params) — deixa a conversa PENDENTE (handoff; mensagem nova do cliente NÃO reabre)."
+        "description": "CADA item de actions DEVE ser um OBJETO {action_name (string), action_params (array)} — NUNCA um texto/string solto. Ex.: [{\"action_name\":\"send_message\",\"action_params\":[\"Oi\"]}]. [{action_name, action_params[]}] Actions novas (2026-07-21): 'update_contact_attribute' e 'update_conversation_attribute' — action_params: [{attribute_key, value}], value aceita texto fixo OU variável Liquid (ex. {{contact.phone_number}}); grava atributo personalizado com MERGE (não apaga os demais) e passa pelo porteiro de data. 'pending_conversation' (2026-07-20, sem params) — deixa a conversa PENDENTE (handoff; mensagem nova do cliente NÃO reabre). ATENCAO — 'send_whatsapp_template': action_params: [{name, id, language, category, processed_params}]. 'name' e OBRIGATORIO e e o nome EXATO do modelo aprovado na Meta (o envio acontece por ele); 'language' precisa bater com o idioma aprovado (padrao pt_BR); processed_params: {\"body\": {\"1\": \"{{contact.first_name}}\"}}. NUNCA use template_name/template_id/template_category/template_language — esse e o formato dos nos do FlowBuilder e aqui e IGNORADO: a regra salva com sucesso, aparece na tela e NAO ENVIA NADA, sem erro nem log (incidente real conta 39 em 02/08/2026: 14h sem enviar, 9 leads perdidos). Confira o modelo antes com lionchat_inboxes_whatsapp_templates_list. So funciona em caixa WhatsApp API Oficial (Cloud). REGRA GERAL: action_params e SEMPRE um array (o backend le params[0]) e seu CONTEUDO nao e validado pela API. Se nao souber o formato de uma acao, leia uma regra existente com lionchat_automation_rules_show e copie — nunca invente nome de chave. Formato de TODAS as acoes no resource 'conversation-flows'."
       },
       {
         "name": "active",
@@ -10189,14 +10189,14 @@
         "type": "array",
         "location": "body",
         "required": false,
-        "description": "Condicoes"
+        "description": "Condicoes REGRA DO CONECTOR (query_operator) — LEIA ANTES DE GRAVAR: o conector liga a condicao com a SEGUINTE, logo a ULTIMA condicao TEM que ter query_operator: null (condicao UNICA tambem = null). Nas demais: 'AND' ou 'OR'. A API valida o VALOR do conector mas NAO a POSICAO — conector na ultima condicao SALVA COM SUCESSO, aparece certo na tela e a regra NUNCA dispara. Incidente real: 8 regras criadas pelo conector de IA entre 26 e 30/07/2026 em 3 contas, todas com conector na ultima condicao, todas nasceram mortas (732 erros/hora medidos em producao 03/08; a conta 62 ficou com as 6 regras de etiquetagem automatica paradas). attribute_key precisa ser campo padrao OU atributo personalizado que EXISTA na conta (senao a regra inteira falha na validacao: 'Automation conditions <chave> not supported') — conferir antes com lionchat_custom_attributes_list; atributo personalizado exige tambem custom_attribute_type ('conversation_attribute' ou 'contact_attribute'). filter_operator: equal_to, not_equal_to, contains, does_not_contain, is_present, is_not_present, is_greater_than, is_less_than, starts_with, days_before, days_ago, last_days, today, yesterday — cada campo aceita so um subconjunto. Na duvida, leia uma regra que ja funciona com lionchat_automation_rules_show e copie o formato. Detalhe no resource 'conversation-flows'."
       },
       {
         "name": "actions",
         "type": "array",
         "location": "body",
         "required": false,
-        "description": "CADA item de actions DEVE ser um OBJETO {action_name (string), action_params (array)} — NUNCA um texto/string solto. Ex.: [{\"action_name\":\"send_message\",\"action_params\":[\"Oi\"]}]. Acoes Actions novas (2026-07-21): 'update_contact_attribute' e 'update_conversation_attribute' — action_params: [{attribute_key, value}], value aceita texto fixo OU variável Liquid (ex. {{contact.phone_number}}); grava atributo personalizado com MERGE (não apaga os demais) e passa pelo porteiro de data. 'pending_conversation' (2026-07-20, sem params) — deixa a conversa PENDENTE (handoff; mensagem nova do cliente NÃO reabre)."
+        "description": "CADA item de actions DEVE ser um OBJETO {action_name (string), action_params (array)} — NUNCA um texto/string solto. Ex.: [{\"action_name\":\"send_message\",\"action_params\":[\"Oi\"]}]. Acoes Actions novas (2026-07-21): 'update_contact_attribute' e 'update_conversation_attribute' — action_params: [{attribute_key, value}], value aceita texto fixo OU variável Liquid (ex. {{contact.phone_number}}); grava atributo personalizado com MERGE (não apaga os demais) e passa pelo porteiro de data. 'pending_conversation' (2026-07-20, sem params) — deixa a conversa PENDENTE (handoff; mensagem nova do cliente NÃO reabre). ATENCAO — 'send_whatsapp_template': action_params: [{name, id, language, category, processed_params}]. 'name' e OBRIGATORIO e e o nome EXATO do modelo aprovado na Meta (o envio acontece por ele); 'language' precisa bater com o idioma aprovado (padrao pt_BR); processed_params: {\"body\": {\"1\": \"{{contact.first_name}}\"}}. NUNCA use template_name/template_id/template_category/template_language — esse e o formato dos nos do FlowBuilder e aqui e IGNORADO: a regra salva com sucesso, aparece na tela e NAO ENVIA NADA, sem erro nem log (incidente real conta 39 em 02/08/2026: 14h sem enviar, 9 leads perdidos). Confira o modelo antes com lionchat_inboxes_whatsapp_templates_list. So funciona em caixa WhatsApp API Oficial (Cloud). REGRA GERAL: action_params e SEMPRE um array (o backend le params[0]) e seu CONTEUDO nao e validado pela API. Se nao souber o formato de uma acao, leia uma regra existente com lionchat_automation_rules_show e copie — nunca invente nome de chave. Formato de TODAS as acoes no resource 'conversation-flows'."
       }
     ],
     "returns": "regra de automação atualizado",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "description": "MCP server for LionChat API — 547 tools + 10 resources + 9 prompts. Audit-log aware, completion API, progress notifications.",
   "type": "module",
   "main": "dist/index.js",