@lionchat/mcp-server 0.5.6 → 0.5.8

package/dist/docs/resources/best-practices.md

@@ -261,6 +261,48 @@ Pra dados fixos que se repetem (slogans, endereços, horários):
 
 Nunca hard-code esses dados em respostas geradas.
 
+## Templates WhatsApp com variáveis do sistema (auto-preenchimento) (2026-06)
+
+Ao criar/editar um template WhatsApp (`inboxes_whatsapp_templates_create` / `_create_2`), o corpo usa
+variáveis posicionais `{{1}}`, `{{2}}`. Por padrão elas são **manuais** (o atendente digita o valor no
+envio). Pra deixar uma variável **auto-preenchida** com um campo do contato/conversa, mande o parâmetro
+opcional `variable_mapping` junto.
+
+- Formato: objeto com chave = posição da variável (`"1"`, `"2"`...) e valor = `{ source, field, label }`.
+- Só entram no mapping as que devem auto-preencher; as demais `{{N}}` continuam manuais.
+- O `variable_mapping` é salvo localmente (NÃO vai pra Meta) e usado no momento do envio.
+
+Exemplo — `{{1}}` vira o primeiro nome do contato:
+
+```json
+{
+  "components": [
+    { "type": "BODY", "text": "Olá {{1}}! Sua oferta de {{2}} está ativa.",
+      "example": { "body_text": [["Maria", "20%"]] } }
+  ],
+  "variable_mapping": {
+    "1": { "source": "contact", "field": "name.split.first", "label": "Primeiro nome" }
+  }
+}
+```
+
+Fontes/campos disponíveis (`source` / `field`):
+
+| Variável | source | field |
+|---|---|---|
+| Nome completo | contact | name |
+| Primeiro nome | contact | name.split.first |
+| Sobrenome | contact | name.split[1..] |
+| Telefone | contact | phone_number |
+| E-mail | contact | email |
+| Atendente | conversation | assignee.name |
+| Equipe | conversation | team.name |
+| Nome da conta | account | name |
+| Campo personalizado | contact | custom_attributes.CHAVE |
+
+Lembrete: todo template recém-criado pelo MCP só mostra o texto na tela depois de **sincronizar**
+(o MCP cria na Meta, mas o "puxar de volta" o conteúdo é o que a tela faz com o botão Sincronizar).
+
 ## Status codes a respeitar
 
 | Code | O que fazer |

package/dist/docs/resources/flowbuilder-design-guide.md

@@ -248,7 +248,7 @@ No editor visual esses destinos só aparecem quando a validação bate (computed
 | `conversation_has_agent` / `conversation_no_agent` / `conversation_not_agent` | agente atribuído |
 | `contact_has_label` / `contact_no_label` / `conversation_has_label` / `conversation_no_label` | labels |
 | `kanban_exists` / `kanban_in_stage` / `kanban_won` / `kanban_lost` | card no funil (usa `funnel_id` + `stage`) |
-| `card_attr_equals` / `card_attr_contains` | atributo do card (`attrSource: 'card'` + `attr_key`) |
+| `card_attr_equals` / `card_attr_contains` | atributo do card (`attrSource: 'card'` + `attr_key`; aceita `card_source: 'trigger'` p/ ler o card que iniciou o flow) |
 | `pagetrack_visited` / `pagetrack_event` | LionTrack |
 | `sla_check` | status do SLA da conversa (usa `value` = código fixo; ver abaixo) |
 
@@ -327,6 +327,8 @@ Ex.: `{ "operator": "sla_check", "value": "frt_breached" }`. "Estourado" = o mon
 
 **Handles que SAEM:** `success`. Não tem handle `error` — falhas viram warning silencioso e o flow continua.
 
+**`card_source` (blocos de card) — opcional:** as ações de card aceitam `card_source`: `'funnel'` (default — procura o card pelo `funnel_id`) ou `'trigger'` (usa o card que DISPAROU o flow, em flows iniciados por `card_created`/`card_moved`/`card_won`/`card_lost`). Com `'trigger'`, `funnel_id` deixa de ser obrigatório — EXCETO em `move_kanban_stage`/`create_kanban_item`, cujo funil/etapa são o DESTINO. Sem card-gatilho disponível, a ação é pulada (não cai no fallback de funil). Aplica-se a `move_kanban_stage`, `set_won`/`set_lost`/`set_open`, `assign_agent_card`, `add_card_note`, `update_attribute` (com `attr_source: 'card'`) e às condições `card_attr_equals`/`card_attr_contains` (gravando `card_source` na própria regra).
+
 **`update_attribute` — campos EXATOS:** `attr_source` (`'contact'`, `'conversation'` ou `'card'`), `attr_key` (nome do atributo), `attr_value` (valor). NÃO existem `entity`/`key`/`value` — esses são ignorados e não salvam nada.
 
 **Somar/subtrair NÃO é operação dedicada** — é filtro Liquid no próprio `attr_value`. O valor é resolvido como template antes de salvar. Exemplos:

package/endpoints.json

@@ -1901,6 +1901,13 @@
         "location": "body",
         "required": false,
         "description": "Arquivos anexos"
+      },
+      {
+        "name": "content_attributes",
+        "type": "object",
+        "location": "body",
+        "required": false,
+        "description": "Atributos livres da mensagem (objeto). Chaves uteis: coex_backup=true => envia fora da janela de 24h via sessao WAHA so-envio (caixa Cloud em coexistencia); reply_mode='public'|'private' + in_reply_to_comment_id => responde a um comentario do Instagram; in_reply_to => cita/responde outra mensagem pelo id."
       }
     ],
     "returns": "mensagem criada",
@@ -2295,7 +2302,7 @@
         "type": "object",
         "location": "body",
         "required": false,
-        "description": "Configurações"
+        "description": "Objeto de configuracoes do funil. Chaves: goals[], agents[] e automations[] (automacoes do funil). Cada automacao: {id, enabled, trigger_type: 'card_created'|'stage_moved'|'status_change', trigger_value (id da etapa p/ stage_moved; status p/ status_change; vazio p/ card_created), action: 'move_to_stage'|'assign_agent'|'create_note'|'update_checklist'|'apply_checklist_template'|'notify_team'|'duplicate_item'|'send_webhook', action_config: {} (ex.: move_to_stage->{stage}; assign_agent->{agent_id}; create_note->{note_text}; apply_checklist_template->{template_id}; notify_team->{message}; send_webhook->{webhook_url}; duplicate_item->{funnel_id,stage})}. ATENCAO: gravar settings SUBSTITUI o objeto inteiro — leia o funil (show) e reenvie settings completo (goals+agents+automations)."
       },
       {
         "name": "funnel.global_custom_attributes",
@@ -2374,7 +2381,7 @@
         "type": "object",
         "location": "body",
         "required": false,
-        "description": "Configurações"
+        "description": "Objeto de configuracoes do funil. Chaves: goals[], agents[] e automations[] (automacoes do funil). Cada automacao: {id, enabled, trigger_type: 'card_created'|'stage_moved'|'status_change', trigger_value (id da etapa p/ stage_moved; status p/ status_change; vazio p/ card_created), action: 'move_to_stage'|'assign_agent'|'create_note'|'update_checklist'|'apply_checklist_template'|'notify_team'|'duplicate_item'|'send_webhook', action_config: {} (ex.: move_to_stage->{stage}; assign_agent->{agent_id}; create_note->{note_text}; apply_checklist_template->{template_id}; notify_team->{message}; send_webhook->{webhook_url}; duplicate_item->{funnel_id,stage})}. ATENCAO: gravar settings SUBSTITUI o objeto inteiro — leia o funil (show) e reenvie settings completo (goals+agents+automations)."
       }
     ],
     "returns": "funil atualizado",
@@ -3997,6 +4004,13 @@
         "location": "body",
         "required": false,
         "description": "BOTAO DE PANICO: true pausa TODA a IA do assistente (respostas, follow-ups, callbacks) sem perder config. Top-level, auditado"
+      },
+      {
+        "name": "config.follow_up_skip_conditions",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Condicoes para a IA NAO fazer follow-up (ate 3). Array de objetos, ex.: {type, operator, attribute, value, labels:[]}."
       }
     ],
     "returns": "assistente AI criado (com novo ID)",
@@ -4208,6 +4222,13 @@
         "location": "body",
         "required": false,
         "description": "BOTAO DE PANICO: true pausa TODA a IA do assistente (respostas, follow-ups, callbacks) sem perder config. Top-level, auditado"
+      },
+      {
+        "name": "config.follow_up_skip_conditions",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Condicoes para a IA NAO fazer follow-up (ate 3). Array de objetos, ex.: {type, operator, attribute, value, labels:[]}."
       }
     ],
     "returns": "assistente AI atualizado",
@@ -6191,7 +6212,15 @@
     "title": "Listar Threads Copilot",
     "description": "Lista as threads do Copilot.",
     "category": "Assistentes",
-    "params": [],
+    "params": [
+      {
+        "name": "conversation_id",
+        "type": "integer",
+        "location": "query",
+        "required": false,
+        "description": "Filtra as threads do Copiloto pela conversa (conversation_display_id)."
+      }
+    ],
     "returns": "meta (contadores globais) + payload (array de assistentes AI)",
     "common_use_cases": [
       "Dashboard: contar/exibir assistentes AI",
@@ -14521,6 +14550,13 @@
         "location": "body",
         "required": true,
         "description": "Componentes do template"
+      },
+      {
+        "name": "variable_mapping",
+        "type": "object",
+        "location": "body",
+        "required": false,
+        "description": "Opcional. Mapeia variaveis {{N}} do corpo a campos do sistema para auto-preenchimento no envio (NAO vai para a Meta, fica salvo localmente). Chave = posicao da variavel (\"1\", \"2\"...), valor = objeto {source, field, label}. Ex: {\"1\": {\"source\": \"contact\", \"field\": \"name.split.first\", \"label\": \"Primeiro nome\"}}. Variavel sem mapping continua manual (digitada no envio). Fontes/campos: contact/name (Nome completo), contact/name.split.first (Primeiro nome), contact/name.split[1..] (Sobrenome), contact/phone_number, contact/email, conversation/assignee.name (Atendente), conversation/team.name (Equipe), account/name, ou contact/custom_attributes.CHAVE para campo personalizado."
       }
     ],
     "returns": "template WhatsApp criado (com novo ID)",
@@ -14640,6 +14676,13 @@
         "location": "body",
         "required": false,
         "description": "Componentes atualizados"
+      },
+      {
+        "name": "variable_mapping",
+        "type": "object",
+        "location": "body",
+        "required": false,
+        "description": "Opcional. Mapeia variaveis {{N}} a campos do sistema para auto-preenchimento no envio (NAO vai para a Meta). Chave = posicao da variavel (\"1\", \"2\"...), valor = objeto {source, field, label}. Ex: {\"1\": {\"source\": \"contact\", \"field\": \"name.split.first\", \"label\": \"Primeiro nome\"}}. Mesmas fontes/campos do endpoint de criacao."
       }
     ],
     "returns": "{ success: true }",
@@ -14654,6 +14697,33 @@
       "lionchat_inboxes_whatsapp_templates_destroy"
     ]
   },
+  {
+    "id": "lionchat_inboxes_sync_templates",
+    "method": "POST",
+    "path": "/api/v1/accounts/{account_id}/inboxes/{inbox_id}/sync_templates",
+    "title": "Sincronizar Templates WhatsApp",
+    "description": "Sincroniza (puxa) os templates de WhatsApp da Meta para a caixa, atualizando nome, corpo e status no LionChat. SOMENTE Channel::Whatsapp Cloud. Use logo apos criar/editar um template via API: a criacao retorna so id/status e o conteudo so aparece na tela depois deste sync.",
+    "category": "Templates WhatsApp",
+    "params": [
+      {
+        "name": "inbox_id",
+        "type": "integer",
+        "location": "path",
+        "required": true,
+        "description": "ID da inbox"
+      }
+    ],
+    "returns": "{ message: 'Template sync initiated successfully' } — dispara o job de sincronizacao",
+    "common_use_cases": [
+      "Tornar visivel um template recem-criado via API (sai do estado vazio)",
+      "Atualizar status (aprovado/recusado) dos templates"
+    ],
+    "related_tools": [
+      "lionchat_inboxes_whatsapp_templates_create",
+      "lionchat_inboxes_whatsapp_templates_create_2",
+      "lionchat_inboxes_whatsapp_templates_list"
+    ]
+  },
   {
     "id": "lionchat_inboxes_csat_template_list",
     "method": "GET",
@@ -18131,9 +18201,73 @@
     "method": "POST",
     "path": "/api/v1/accounts/{account_id}/kanban_config",
     "title": "Criar Configuracao Kanban",
-    "description": "Cria a configuracao do Kanban. Cria novo config Kanban. Valida unicidade quando aplicável. Retorna o config Kanban criado com ID atribuído.",
+    "description": "Cria a configuracao do Kanban da conta (singleton). Aceita: checklist_templates (templates de checklist reutilizaveis aplicados aos cards), win_reasons/loss_reasons (motivos de ganho/perda), global_custom_attributes (atributos dos cards), config (preferencias) e webhook (url/secret/events).",
     "category": "Config Kanban",
-    "params": [],
+    "params": [
+      {
+        "name": "kanban_config.checklist_templates",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Templates de checklist reutilizaveis aplicaveis aos cards. Formato: [{id, name, items:[{id, text}]}]"
+      },
+      {
+        "name": "kanban_config.win_reasons",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Motivos de ganho do funil. Formato: [{id, title}]"
+      },
+      {
+        "name": "kanban_config.loss_reasons",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Motivos de perda do funil. Formato: [{id, title}]"
+      },
+      {
+        "name": "kanban_config.global_custom_attributes",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Atributos personalizados globais dos cards. Formato: [{name, type, is_list, list_values:[]}]"
+      },
+      {
+        "name": "kanban_config.config",
+        "type": "object",
+        "location": "body",
+        "required": false,
+        "description": "Preferencias do Kanban: title, default_view, auto_assignment, notifications_enabled, support_email, support_phone, support_chat_hours, support_chat_enabled, dragbar_enabled, quick_message_enabled, list_view_enabled, agenda_view_enabled"
+      },
+      {
+        "name": "kanban_config.enabled",
+        "type": "boolean",
+        "location": "body",
+        "required": false,
+        "description": "Habilita/desabilita a config (afeta o webhook)"
+      },
+      {
+        "name": "kanban_config.webhook_url",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "URL do webhook do Kanban"
+      },
+      {
+        "name": "kanban_config.webhook_secret",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Segredo HMAC do webhook"
+      },
+      {
+        "name": "kanban_config.webhook_events",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Eventos do webhook habilitados (array de strings)"
+      }
+    ],
     "returns": "config Kanban criado (com novo ID)",
     "common_use_cases": [
       "Cadastro inicial de config Kanban",
@@ -18151,9 +18285,73 @@
     "method": "PUT",
     "path": "/api/v1/accounts/{account_id}/kanban_config",
     "title": "Atualizar Configuracao Kanban",
-    "description": "Atualiza a configuracao do Kanban. Atualiza campos do config Kanban existente. Suporta atualização parcial (PATCH) — só campos enviados são alterados.",
+    "description": "Atualiza a configuracao do Kanban da conta. Atualizacao parcial — so os campos enviados mudam. Use para criar/editar checklist_templates (templates de checklist dos cards), win_reasons/loss_reasons (motivos de ganho/perda), global_custom_attributes (atributos dos cards), config (preferencias) e webhook (url/secret/events).",
     "category": "Config Kanban",
-    "params": [],
+    "params": [
+      {
+        "name": "kanban_config.checklist_templates",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Templates de checklist reutilizaveis aplicaveis aos cards. Formato: [{id, name, items:[{id, text}]}]"
+      },
+      {
+        "name": "kanban_config.win_reasons",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Motivos de ganho do funil. Formato: [{id, title}]"
+      },
+      {
+        "name": "kanban_config.loss_reasons",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Motivos de perda do funil. Formato: [{id, title}]"
+      },
+      {
+        "name": "kanban_config.global_custom_attributes",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Atributos personalizados globais dos cards. Formato: [{name, type, is_list, list_values:[]}]"
+      },
+      {
+        "name": "kanban_config.config",
+        "type": "object",
+        "location": "body",
+        "required": false,
+        "description": "Preferencias do Kanban: title, default_view, auto_assignment, notifications_enabled, support_email, support_phone, support_chat_hours, support_chat_enabled, dragbar_enabled, quick_message_enabled, list_view_enabled, agenda_view_enabled"
+      },
+      {
+        "name": "kanban_config.enabled",
+        "type": "boolean",
+        "location": "body",
+        "required": false,
+        "description": "Habilita/desabilita a config (afeta o webhook)"
+      },
+      {
+        "name": "kanban_config.webhook_url",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "URL do webhook do Kanban"
+      },
+      {
+        "name": "kanban_config.webhook_secret",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Segredo HMAC do webhook"
+      },
+      {
+        "name": "kanban_config.webhook_events",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Eventos do webhook habilitados (array de strings)"
+      }
+    ],
     "returns": "config Kanban atualizado",
     "common_use_cases": [
       "Edição parcial de config Kanban",
@@ -24323,6 +24521,84 @@
       "lionchat_inboxes_whatsapp_history_status"
     ]
   },
+  {
+    "id": "lionchat_inboxes_coex_backup_connect",
+    "method": "POST",
+    "path": "/api/v1/accounts/{account_id}/inboxes/{inbox_id}/coex_backup/connect",
+    "title": "Conectar Saida de Emergencia (Coex)",
+    "description": "Provisiona/conecta a sessao WAHA so-envio (retorna QR) de uma caixa WhatsApp Cloud em coexistencia, usada para enviar texto fora da janela de 24h. Requer admin + feature 'coexistence_backup_send' + caixa Cloud em coexistencia.",
+    "category": "Caixas de Entrada",
+    "params": [
+      {
+        "name": "inbox_id",
+        "type": "integer",
+        "location": "path",
+        "required": true,
+        "description": "ID da caixa de entrada (inbox)"
+      }
+    ],
+    "returns": "Estado da sessao de emergencia (state, qr, connected)",
+    "common_use_cases": [
+      "Ativar o envio fora da janela de 24h numa caixa Cloud",
+      "Exibir o QR para parear o numero de emergencia"
+    ],
+    "related_tools": [
+      "lionchat_inboxes_coex_backup_status",
+      "lionchat_inboxes_coex_backup_disconnect"
+    ]
+  },
+  {
+    "id": "lionchat_inboxes_coex_backup_status",
+    "method": "GET",
+    "path": "/api/v1/accounts/{account_id}/inboxes/{inbox_id}/coex_backup/status",
+    "title": "Status da Saida de Emergencia (Coex)",
+    "description": "Retorna o estado da sessao WAHA so-envio da caixa (state, qr, connected). Nunca levanta erro. Requer admin + feature 'coexistence_backup_send'.",
+    "category": "Caixas de Entrada",
+    "params": [
+      {
+        "name": "inbox_id",
+        "type": "integer",
+        "location": "path",
+        "required": true,
+        "description": "ID da caixa de entrada (inbox)"
+      }
+    ],
+    "returns": "{ state, qr, connected }",
+    "common_use_cases": [
+      "Verificar se a saida de emergencia esta conectada",
+      "Buscar o QR atual durante o pareamento"
+    ],
+    "related_tools": [
+      "lionchat_inboxes_coex_backup_connect",
+      "lionchat_inboxes_coex_backup_disconnect"
+    ]
+  },
+  {
+    "id": "lionchat_inboxes_coex_backup_disconnect",
+    "method": "POST",
+    "path": "/api/v1/accounts/{account_id}/inboxes/{inbox_id}/coex_backup/disconnect",
+    "title": "Desconectar Saida de Emergencia (Coex)",
+    "description": "Desconecta/destroi a sessao WAHA so-envio da caixa Cloud em coexistencia. Requer admin + feature 'coexistence_backup_send'.",
+    "category": "Caixas de Entrada",
+    "params": [
+      {
+        "name": "inbox_id",
+        "type": "integer",
+        "location": "path",
+        "required": true,
+        "description": "ID da caixa de entrada (inbox)"
+      }
+    ],
+    "returns": "Resultado da desconexao",
+    "common_use_cases": [
+      "Desligar o envio fora da janela de 24h",
+      "Limpar a sessao de emergencia da caixa"
+    ],
+    "related_tools": [
+      "lionchat_inboxes_coex_backup_connect",
+      "lionchat_inboxes_coex_backup_status"
+    ]
+  },
   {
     "id": "lionchat_conversations_toggle_block",
     "method": "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionchat/mcp-server",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "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",