@lionchat/mcp-server 0.5.5 → 0.5.7

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

@@ -166,6 +166,16 @@ Como a coleta de dados/cenários funciona hoje (importante pra diagnosticar "IA
 - O admin pode FIXAR o parâmetro de uma ferramenta no cenário (campo scenario.tool_bindings): quais mídias enviar, qual funil+etapa do card, quais agendas no agendamento. "Deixar a IA decidir" = binding vazio.
 - Quando UM cenário fixa a tool, a execução vira determinística (a IA não escolhe): mídia e kanban são aplicados pós-turno pelo BindingResolver (ordem texto→ação, sem duplicar, idempotente); o agendamento força/restringe a agenda mas a IA ainda define data/hora.
 - Via MCP: scenarios_create/update persiste binding de send_media_asset e create_kanban_item/move_kanban_item (re-escopados por conta). O binding de create_booking NÃO é aceito pela API — pra limitar agendas via MCP, use config.booking_event_type_ids no assistente (captain_assistants_update).
+- Receita pra criar/editar cenário com binding via MCP (scenarios_create / scenarios_update): (1) o corpo vai SEMPRE embrulhado em `scenario`; (2) a instrução PRECISA mencionar a ferramenta como link markdown `[Rótulo](tool://slug)` — menção crua `(tool://slug)` NÃO conta e o binding é descartado no salvamento; (3) envie `tool_bindings` com o shape: `send_media_asset` → `{ "asset_ids": [Int] }`, `create_kanban_item`/`move_kanban_item` → `{ "funnel_id": Int, "stage": "<chave da etapa>" }`. Não precisa mandar `tools` (é auto-extraído da instrução e sobrescrito). `create_booking` NÃO entra em tool_bindings pela API.
+
+## Variáveis {{ }} nas instruções do AI Agente (2026-06)
+
+As instruções aceitam variáveis Liquid `{{ }}` que chegam JÁ PREENCHIDAS com os dados reais do contato/conversa do atendimento — vale pra instrução base do assistente (`config.instructions`) e pra instrução de cada cenário (`scenario.instruction`). O texto é gravado como está (sem sanitização); cap de 20.000 chars na base.
+
+- Contato: `{{contact.name}}`, `{{contact.first_name}}`, `{{contact.last_name}}`, `{{contact.email}}`, `{{contact.phone}}`, `{{contact.cpf}}`, `{{contact.cnpj}}`, `{{contact.rg}}`, `{{contact.date_of_birth}}`, `{{contact.profession}}`, `{{contact.address.city}}` (e `.cep`/`.street`/`.number`/`.neighborhood`/`.state`...), `{{contact.custom_attribute.<chave>}}`.
+- Conversa: `{{conversation.display_id}}`, `{{conversation.custom_attribute.<chave>}}`.
+- Variável sem valor sai vazia (não quebra). Texto SEM `{{` sai idêntico (preserva o cache do prompt) — só use variável quando agregar.
+- ATENÇÃO: variável de CONTA NÃO funciona aqui — `{{account.custom_attribute.<chave>}}` (slogan, endereço...) sai VAZIA dentro das instruções do AI Agente (o contexto só tem `contact` e `conversation`, proteção contra vazar secret). Pra um valor fixo da empresa no prompt, escreva o valor literal no texto.
 
 ## Conhecimento passivo da IA: FAQ + artigos (RAG) (2026-06)
 
@@ -242,13 +252,57 @@ campanha e mostre a contagem ao usuário — estimativa e disparo usam o mesmo m
 
 ## Variáveis de conta (account_variables)
 
-Pra dados que se repetem (slogans, endereços, horários):
-- `account_variables_create` UMA vez
-- Use em templates com `{{slogan}}`, `{{endereco}}`
-- Atualiza UMA vez, propaga pra todo lugar
+Pra dados fixos que se repetem (slogans, endereços, horários):
+- `account_variables_create` UMA vez — campos: `attribute_display_name` (rótulo), `attribute_key` (a chave usada no `{{ }}`), `attribute_display_type` (`text`; use `secret` pra token/senha), `value`. Admin-only.
+- Use em templates com a sintaxe COMPLETA `{{ account.custom_attribute.<attribute_key> }}` (ex: `{{ account.custom_attribute.slogan }}`). NÃO existe atalho `{{slogan}}` solto — sem o prefixo `account.custom_attribute.` não resolve.
+- Resolve em: mensagens, respostas prontas, campanhas e automações. NÃO resolve nas instruções do AI Agente (base/cenário) — ali só `contact.*` e `conversation.*`.
+- `secret` nunca aparece em template (sai vazio); só resolve em nós API Request do FlowBuilder.
+- Atualiza UMA vez, propaga pra todo lugar.
 
 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/endpoints.json

@@ -5761,6 +5761,20 @@
         "location": "body",
         "required": false,
         "description": "Toggle ativo/inativo (default true)"
+      },
+      {
+        "name": "tools",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Lista de slugs das ferramentas do cenario (ex: [\"send_media_asset\",\"create_kanban_item\"]). NORMALMENTE NAO precisa enviar: e DERIVADO automaticamente das mencoes [Rotulo](tool://slug) na instrucao e SOBRESCRITO no salvamento. Quem governa e o texto da instrucao."
+      },
+      {
+        "name": "tool_bindings",
+        "type": "object",
+        "location": "body",
+        "required": false,
+        "description": "Parametro FIXADO por ferramenta (admin pre-define em vez de a IA escolher). Shapes aceitos: send_media_asset -> { \"asset_ids\": [Int] }; create_kanban_item e move_kanban_item -> { \"funnel_id\": Int, \"stage\": \"<chave da etapa>\" }. create_booking NAO e aceito aqui (para restringir agendas use config.booking_event_type_ids no assistente via captain_assistants_update). O binding so COLA se a ferramenta estiver mencionada como [Rotulo](tool://slug) na instrucao; senao e podado no salvamento. IDs de outra conta sao descartados (re-escopo por conta)."
       }
     ],
     "returns": "assistente AI criado (com novo ID)",
@@ -5860,6 +5874,20 @@
         "location": "body",
         "required": false,
         "description": "Toggle ativo/inativo"
+      },
+      {
+        "name": "tools",
+        "type": "array",
+        "location": "body",
+        "required": false,
+        "description": "Lista de slugs das ferramentas do cenario (ex: [\"send_media_asset\",\"create_kanban_item\"]). NORMALMENTE NAO precisa enviar: e DERIVADO automaticamente das mencoes [Rotulo](tool://slug) na instrucao e SOBRESCRITO no salvamento. Quem governa e o texto da instrucao."
+      },
+      {
+        "name": "tool_bindings",
+        "type": "object",
+        "location": "body",
+        "required": false,
+        "description": "Parametro FIXADO por ferramenta (admin pre-define em vez de a IA escolher). Shapes aceitos: send_media_asset -> { \"asset_ids\": [Int] }; create_kanban_item e move_kanban_item -> { \"funnel_id\": Int, \"stage\": \"<chave da etapa>\" }. create_booking NAO e aceito aqui (para restringir agendas use config.booking_event_type_ids no assistente via captain_assistants_update). O binding so COLA se a ferramenta estiver mencionada como [Rotulo](tool://slug) na instrucao; senao e podado no salvamento. IDs de outra conta sao descartados (re-escopo por conta)."
       }
     ],
     "returns": "assistente AI atualizado",
@@ -5872,7 +5900,8 @@
       "lionchat_captain_assistants_list",
       "lionchat_captain_assistants_create",
       "lionchat_captain_assistants_show"
-    ]
+    ],
+    "body_wrapper": "scenario"
   },
   {
     "id": "lionchat_captain_assistants_destroy_1",
@@ -14492,6 +14521,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)",
@@ -14611,6 +14647,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 }",
@@ -14625,6 +14668,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",

package/package.json

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