@lionchat/mcp-server 0.5.8 → 0.5.9

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

@@ -261,6 +261,57 @@ Pra dados fixos que se repetem (slogans, endereços, horários):
 
 Nunca hard-code esses dados em respostas geradas.
 
+## Variável dinâmica: atributo do contato escolhe a variável da conta (2026-07)
+
+Receita pra quando a mensagem precisa puxar um valor que DEPENDE de um campo do contato.
+Exemplo clássico: contato tem `unidade_de_atendimento` (Sorocaba) e a mensagem deve trazer
+o endereço DAQUELA unidade sem o atendente escolher nada.
+
+A técnica é busca indireta (indirect lookup) em Liquid: montar o NOME da variável da conta
+usando o VALOR do atributo do contato e buscar por colchete `account.custom_attribute[chave]`.
+
+### Peças a criar (todas têm tool no MCP)
+
+1. Atributo de contato tipo lista (`custom_attributes_create`): ex. `unidade_de_atendimento`
+   com valores `sorocaba`, `tatuape`... (slugs limpos: sem acento, sem espaço).
+2. Uma variável da conta por opção (`account_variables_create`), nomeada `prefixo_` + valor:
+   `endereco_sorocaba`, `endereco_tatuape`...
+3. Resposta pronta (`canned_responses_create`) usando a sintaxe abaixo.
+
+### Sintaxe que funciona
+
+```text
+Seu atendimento será na unidade {{contact.custom_attribute.unidade_de_atendimento}}.
+Endereço: {% assign chave = "endereco_" | append: contact.custom_attribute.unidade_de_atendimento | downcase %}{% echo account.custom_attribute[chave] %}
+```
+
+### Regras críticas (confirmadas no código)
+
+- A parte dinâmica DEVE usar `{% assign %}` + `{% echo %}` (tags `{% %}`), NUNCA `{{ }}`:
+  a caixa de mensagem substitui/apaga `{{ }}` desconhecido antes de enviar; tags `{% %}`
+  passam intactas e o backend (Liquid 5) resolve na criação da mensagem.
+- Variáveis simples conhecidas (ex. `{{contact.custom_attribute.unidade_de_atendimento}}`)
+  podem ficar em `{{ }}` normalmente.
+- Casamento da chave: o valor do atributo, em minúsculo, precisa bater EXATAMENTE com o
+  final do nome da variável da conta (`sorocaba` -> `endereco_sorocaba`). Por isso os
+  valores da lista devem ser slugs sem acento/espaço. O `| downcase` cobre maiúsculas,
+  mas NÃO remove acento nem espaço.
+- NÃO envolva o trecho Liquid em crase/backticks: código entre crases vira `{% raw %}`
+  (não processa) — a mensagem sairia com o código literal.
+- Variável da conta tipo `secret` sai VAZIA em mensagem (bloqueio de segurança; só resolve
+  em nó API Request do FlowBuilder).
+- Onde resolve: mensagens outgoing, respostas prontas, campanhas e automações. NÃO resolve
+  nas instruções do AI Agente.
+- Se a chave montada não existir, o `{% echo %}` sai vazio (sem erro). Teste com um contato
+  de cada valor da lista antes de entregar.
+
+### Padrão geral (serve pra qualquer caso)
+
+- Atributo do contato = o seletor (unidade, plano, cidade...).
+- Variáveis da conta = a tabela de valores (`endereco_X`, `preco_X`, `link_X`...).
+- Mensagem monta a chave: `"prefixo_" | append: valor_do_contato | downcase` e busca com
+  `account.custom_attribute[chave]`.
+
 ## 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

package/endpoints.json

@@ -7163,7 +7163,7 @@
         "type": "string",
         "location": "body",
         "required": false,
-        "description": "Modo de atribuição de conversas no time"
+        "description": "Modo de atribuicao de conversas no time. Valores: 'online_only' (padrao — so atribui a agentes com status online no momento) ou 'include_offline' (rodizio entre TODOS os agentes do time, mesmo offline)."
       }
     ],
     "returns": "time/equipe criado (com novo ID)",
@@ -7217,7 +7217,7 @@
         "type": "string",
         "location": "body",
         "required": false,
-        "description": "Modo de atribuição de conversas no time"
+        "description": "Modo de atribuicao de conversas no time. Valores: 'online_only' (padrao — so atribui a agentes com status online no momento) ou 'include_offline' (rodizio entre TODOS os agentes do time, mesmo offline)."
       }
     ],
     "returns": "time/equipe atualizado",
@@ -12958,6 +12958,13 @@
         "required": false,
         "description": "Nome"
       },
+      {
+        "name": "description",
+        "type": "string",
+        "location": "body",
+        "required": false,
+        "description": "Nova descricao do cargo"
+      },
       {
         "name": "permissions",
         "type": "array",
@@ -19902,6 +19909,26 @@
       "lionchat_agents_create"
     ]
   },
+  {
+    "id": "lionchat_agents_list",
+    "method": "GET",
+    "path": "/api/v1/accounts/{account_id}/agents",
+    "title": "Listar Agentes",
+    "description": "Lista todos os agentes (usuarios) da conta. Retorna id, name, email, availability_status, confirmed, role (agent ou administrator) e, no Enterprise, custom_role_id (ID do cargo personalizado aplicado ao agente, ou null). Use para descobrir os IDs dos agentes antes de atualizar papel/cargo, reatribuir recursos ou auditar a equipe.",
+    "category": "Agentes",
+    "params": [],
+    "returns": "array de agentes (id, name, email, role, custom_role_id, availability_status, confirmed)",
+    "common_use_cases": [
+      "Descobrir o ID de um agente antes de atualizar ou remover",
+      "Auditar quem e administrador, agente puro ou tem cargo personalizado",
+      "Listar a equipe para aplicar um cargo personalizado em massa"
+    ],
+    "related_tools": [
+      "lionchat_agents_update",
+      "lionchat_agents_create",
+      "lionchat_custom_roles_list"
+    ]
+  },
   {
     "id": "lionchat_agents_create",
     "method": "POST",
@@ -19944,6 +19971,13 @@
         "location": "body",
         "required": false,
         "description": "Define se o agente fica offline automaticamente por inatividade"
+      },
+      {
+        "name": "custom_role_id",
+        "type": "integer",
+        "location": "body",
+        "required": false,
+        "description": "ID do cargo personalizado (custom role) a aplicar ja no convite. Requer Enterprise. Use lionchat_custom_roles_list para obter os IDs. Envie junto com role=agent (cargo personalizado e sempre nivel agente)."
       }
     ],
     "returns": "agente convidado (com novo ID)",
@@ -19957,12 +19991,38 @@
       "lionchat_agents_update"
     ]
   },
+  {
+    "id": "lionchat_agents_resend_invitation",
+    "method": "POST",
+    "path": "/api/v1/accounts/{account_id}/agents/{id}/resend_invitation",
+    "title": "Reenviar Convite do Agente",
+    "description": "Reenvia o e-mail de convite (confirmacao de acesso) para um agente que ainda nao confirmou a conta. Retorna erro se o agente ja estiver confirmado. Rate limit: 1 envio por minuto por agente (429 com retry_after se chamar cedo demais).",
+    "category": "Agentes",
+    "params": [
+      {
+        "name": "id",
+        "type": "integer",
+        "location": "path",
+        "required": true,
+        "description": "ID do agente"
+      }
+    ],
+    "returns": "message: sent + email do agente | 422 se ja confirmado | 429 se rate-limited",
+    "common_use_cases": [
+      "Agente novo nao recebeu ou perdeu o e-mail de convite",
+      "Reativar acesso de agente que nunca confirmou a conta"
+    ],
+    "related_tools": [
+      "lionchat_agents_list",
+      "lionchat_agents_create"
+    ]
+  },
   {
     "id": "lionchat_agents_update",
     "method": "PATCH",
     "path": "/api/v1/accounts/{account_id}/agents/{id}",
     "title": "Atualizar Agente",
-    "description": "Atualiza um agente existente. Campos suportados: name, role (agent ou administrator), availability, auto_offline. Use para promover/rebaixar papel ou ajustar disponibilidade.",
+    "description": "Atualiza um agente existente. Campos suportados: name, role (agent ou administrator), availability, auto_offline e custom_role_id (aplica um cargo personalizado no Enterprise). Use para promover/rebaixar papel, ajustar disponibilidade ou aplicar um cargo personalizado.",
     "category": "Agentes",
     "params": [
       {
@@ -19999,16 +20059,26 @@
         "location": "body",
         "required": false,
         "description": "Define se o agente fica offline automaticamente por inatividade"
+      },
+      {
+        "name": "custom_role_id",
+        "type": "integer",
+        "location": "body",
+        "required": false,
+        "description": "ID do cargo personalizado (custom role) a aplicar ao agente. Requer Enterprise. IMPORTANTE: o backend aplica este campo em TODA atualizacao do agente — se voce atualizar um agente que tem cargo personalizado SEM enviar custom_role_id, o cargo sera REMOVIDO. Ao editar um agente que tem cargo, envie sempre o custom_role_id junto. Use lionchat_custom_roles_list para obter os IDs dos cargos."
       }
     ],
     "returns": "agente atualizado",
     "common_use_cases": [
       "Promover um agente a administrador",
       "Alterar disponibilidade de um agente",
-      "Ajustar o comportamento de offline automático"
+      "Ajustar o comportamento de offline automático",
+      "Aplicar um cargo personalizado (custom role) a um agente"
     ],
     "related_tools": [
-      "lionchat_agents_create"
+      "lionchat_agents_create",
+      "lionchat_agents_list",
+      "lionchat_custom_roles_list"
     ]
   },
   {

package/package.json

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