@lionchat/mcp-server 1.30.0 → 1.31.0

package/dist/docs/instructions.md

@@ -18,8 +18,9 @@ Comprovado em produção (24/07): a sessão que dizia "não há função de list
 - **Famílias principais pra pesquisar:** conversations, conversations_messages, contacts,
   kanban_items, funnels, flows, flow_tools, campaigns, macros, automation_rules, agents, teams,
   inboxes, labels, canned_responses, reports, sla, csat, captain_assistants, captain_documents,
-  scheduled_messages, custom_attributes, webhooks, eclinica_integrations, tasks, notifications,
-  lead_forms (Formulários públicos de captação), signature_documents / signature_envelopes
+  scheduled_messages, custom_attributes, custom_attribute_categories (pastas dos atributos), webhooks, eclinica_integrations, tasks, notifications,
+  lead_forms (Formulários públicos de captação), whatsapp_forms (Formulário do WhatsApp — o nativo
+  da Meta, aberto por botão de modelo), signature_documents / signature_envelopes
   (assinatura ELETRÔNICA de contratos — modelos e contratos enviados).
 - **Fora do MCP por decisão do dono (19/08): assinatura DO PLANO (cobrança), plano, fatura, forma de
   pagamento, cartão, saldo e recarga.** (A assinatura ELETRÔNICA de contratos é outra coisa e TEM
@@ -85,6 +86,12 @@ Account (conta/empresa)
 ### KanbanItem.item_details.priority (string)
 - `urgent`, `high`, `medium`, `low`, `none`
 
+### Situação do card (desde 11/10/2026)
+- Gravada em `item_details.status`: `open`, `won`, `lost`. Na resposta vem também `effective_status`: `open`,
+  **`snoozed`** (adiado — o card sai da coluna até `snoozed_until` e volta sozinho), `won`, `lost`.
+- Adiar: `lionchat_kanban_items_snooze`. Abrir antes da data: `lionchat_kanban_items_unsnooze`. Regras em
+  `lionchat://docs/kanban-deep-dive`, seção "Card adiado".
+
 ### AccountUser.role (string)
 - `agent` (atendente comum)
 - `administrator` (admin/dono)
@@ -424,6 +431,8 @@ Antes de escolher a ferramenta, cheque se a intenção bate com a coluna da dire
 |---|---|---|
 | Listar / ver não lidas | `lionchat_conversations_list` (`conversation_type: 'unread'`) ou `lionchat_conversations_meta` | NÃO use `lionchat_conversations_unread` — é AÇÃO DE ESCRITA (marca como não-lida) |
 | Ver **uma empresa** (quem trabalha la, anotacoes, conversas) e ligar/tirar contatos | `lionchat_companies_show` + `lionchat_companies_contacts_list` / `_create` / `_destroy`, `lionchat_companies_notes_list`, `lionchat_companies_conversations_list` | Ligar pela ficha: `lionchat_contacts_update` com `company_id` (null tira). Cargo da pessoa = `additional_attributes.job_title`. Escolher a empresa troca o texto `company_name` pelo nome dela |
+| Criar / preencher **campo personalizado da empresa** ("Segmento", "Data de fundacao") | `lionchat_custom_attributes_create` com `attribute_model: company_attribute` + `lionchat_companies_update` com `company.custom_attributes {chave: valor}` | So com o modulo Empresas ligado; tipo segredo recusado. Chave que nao existe como atributo de empresa = 422 e nada do pedido grava: crie a definicao ANTES. MESCLA; `null` limpa. Desde 2026-10-16 vira variavel `{{contact.company.custom_attribute.CHAVE}}`, condicao do fluxo (`attrSource: company`), condicao de automacao e filtro de contatos (`custom_attribute_type: company_attribute`) e a IA le — detalhe no resource data-model |
+| Organizar atributos em **categorias** (pastas que abrem e fecham: "Sobre a casa", "Financeiro") | `lionchat_custom_attribute_categories_create` (`name` + `attribute_model`) e depois `lionchat_custom_attribute_categories_assign` (`attribute_key` + `category_id`; `null` tira) | Categoria e OPCIONAL e de UMA aba so (`conversation_attribute`, `contact_attribute`, `company_attribute` ou `kanban_item_attribute` = Card). Criar categoria NAO aceita atributos junto. Card: `attribute_key` = NOME do campo exatamente como gravado. Excluir categoria nunca apaga atributo (voltam para "Sem categoria"). Ver resource data-model |
 | Achar a conversa **de uma pessoa/empresa** (nome, telefone, e-mail, CPF/CNPJ, nº da conversa) | `lionchat_search_list` (`/search/conversations`) ou `lionchat_contacts_search` | RÁPIDO. **NÃO use `lionchat_conversations_search`**: apesar do nome, ele é o legado que procura dentro das mensagens e leva **15 a 22 s** (medido em produção 11/08). O sufixo `_list` aqui é histórico — `lionchat_search_list*` **são buscas**, não listagens; a regra "não baixe tudo com `*_list`" vale para `lionchat_<recurso>_list` |
 | Achar **onde foi dito** algo (palavra dentro da conversa) | `lionchat_search_list_2` (`/search/messages`) | RÁPIDO: índice trigram próprio e teto de tempo em duas fases (2 s / 2 s desde 04/09 — antes a 2ª fase herdava 14 s e o pior caso da seção era 16 s). Estourou as duas, o payload volta com `message_search_interrupted: true` e a lista VAZIA — isso NÃO quer dizer que não existe, quer dizer que não deu tempo: tente de novo. É a substituta certa do `lionchat_conversations_search` |
 | Não sei se o termo é nome de alguém ou algo dito no papo | `lionchat_search_search` (`/search`) | Cobre os dois numa chamada. Opção mais segura quando a intenção é ambígua |

package/dist/docs/resources/agenda-multiplas-unidades.md

@@ -64,7 +64,7 @@ que é sua.
 
 ---
 
-## 4. Página pública (cancelar, remarcar, confirmar presença)
+## 4. Página pública (cancelar, remarcar, confirmar presença, salvar na agenda)
 
 O tipo de evento controla o que o cliente pode fazer:
 
@@ -84,13 +84,53 @@ cliente para fora).
 ### Variáveis da mensagem de abertura
 
 `{{nome}} {{titulo}} {{tipo}} {{agente}} {{data}} {{horario}} {{dia_semana}} {{duracao}}
-{{telefone}} {{email}} {{link_cancelar}} {{link_remarcar}} {{link_confirmar}}`
+{{telefone}} {{email}} {{link_cancelar}} {{link_remarcar}} {{link_confirmar}} {{link_salvar_na_agenda}}`
 
 As chaves são **em português nos dois idiomas** — elas são o identificador, não a tradução.
 Variável desconhecida **sai crua** para o cliente ("Olá {{name}}, ...").
 
 `{{link_confirmar}}` só é útil com `ask_attendance_confirmation` ligado.
 
+### Os QUATRO links da página (16/10)
+
+É UMA página só (`/booking/<conta>/manage/<id>?t=<chave>&action=...`). Cada link abre a mesma página numa
+parte diferente. São quatro links, cada um com um nome na mensagem do Booking e outro no fluxo:
+
+| O link abre na parte de... | Mensagem do Booking (confirmação, lembretes, texto de abertura) | Fluxo (gatilhos `booking_*`) |
+|---|---|---|
+| Confirmar presença | `{{link_confirmar}}` | `{{booking.confirm_url}}` |
+| Remarcar | `{{link_remarcar}}` | `{{booking.reschedule_url}}` |
+| Cancelar | `{{link_cancelar}}` | `{{booking.cancel_url}}` |
+| **Salvar na agenda** (novo, 16/10) | **`{{link_salvar_na_agenda}}`** | **`{{booking.calendar_url}}`** |
+
+**Salvar na agenda** = o cliente põe o compromisso na agenda DELE, sem informar e-mail. Dentro da página há dois
+botões: **Google Agenda** (abre o evento preenchido) e **Agenda do iPhone / Outlook** (arquivo `.ics` com a
+mesma chave do link). Os botões NÃO são variáveis: manda-se só o link e o cliente escolhe lá.
+
+Regras para a IA ao montar mensagem ou fluxo:
+- Para pedir "salve na sua agenda", use SEMPRE o quarto link. Mandar `{{link_cancelar}}` com esse texto abre a
+  parte de CANCELAR a consulta.
+- As outras três partes também mostram "Salvar na minha agenda" entre as opções (um toque a mais).
+- A parte de salvar aparece mesmo quando o tipo não deixa remarcar nem cancelar. Ela NÃO aparece (a página avisa)
+  quando o agendamento ou o compromisso foi cancelado, quando foi concluído e quando a hora já passou.
+- **O compromisso salvo é uma CÓPIA**: nada o atualiza depois. Se a hora mudar, avise o cliente com o gatilho
+  "Agendamento remarcado" (`booking_rescheduled`) + `{{booking.calendar_url}}` (já com a hora nova) e peça que
+  apague o compromisso antigo.
+- **A hora mostrada ao cliente** (mensagem `{{data}}`/`{{horario}}`/`{{duracao}}`, página e agenda salva) é a do
+  COMPROMISSO da Agenda (`account_tasks.scheduled_at`), que é a que o profissional vê.
+- Título salvo: "<tipo> com <profissional> — <empresa>". Sem dado do cliente e sem link com chave dentro.
+- Remarcar ou cancelar pelo link do cliente (ou pela IA) troca a chave: links antigos deixam de abrir. Mudança
+  pela tela da Agenda ou pelo Google não troca a chave, e o link antigo passa a salvar a hora nova.
+- Para mandar o link fora das mensagens automáticas: `tasks_list`/`tasks_show` devolvem `booking_calendar_url`
+  (e `booking_reschedule_url`) no compromisso que veio do Booking; nulo quando não dá para salvar. O painel tem o
+  botão "Link para salvar na agenda" no detalhe do compromisso.
+
+### Remarcar pela IA (16/10)
+
+A ferramenta de remarcar da IA grava o agendamento E o compromisso da Agenda juntos (antes de 16/10 a Agenda ficava
+na hora antiga e o gatilho "Agendamento remarcado" não disparava). Ela não remarca consulta concluída nem com
+"Compareceu" ("Faltou" pode). Pelo Copiloto, marcar, remarcar e cancelar ficam no nome do atendente.
+
 ### Presença é CARIMBO, não status
 
 `attendance` (`attended` / `no_show`) é um campo separado de `status`. Marcar falta **não devolve o
@@ -251,3 +291,5 @@ e se está atrasada.
 | Compromisso da filial no Google da matriz | não acontece mais; se aparecer, a conexão daquela agenda está com `agenda_id` errado |
 | `agendas_create` recusado | recurso `multiple_agendas` desligado ou teto de Extras Manuais atingido |
 | Histórico sumiu ao filtrar a principal | faltou incluir os compromissos com `agenda_id` **nulo** |
+| Cliente pediu para salvar na agenda e caiu na tela de cancelar | a mensagem usou `{{link_cancelar}}`; o certo é `{{link_salvar_na_agenda}}` (fluxo: `{{booking.calendar_url}}`) |
+| Compromisso salvo pelo cliente ficou na hora antiga | é cópia; avise pelo gatilho "Agendamento remarcado" com `{{booking.calendar_url}}` |

package/dist/docs/resources/assinatura-eletronica.md

@@ -29,7 +29,22 @@ Participante: `pending` → `viewed` → `verified` (confirmou o código) → `s
 `created` · `delivered` (link entregue a uma pessoa) · `sent` · `opened` (cada abertura) · `code_requested` ·
 `code_verified` · `signed` (com `ip`, `device`, `location`; `panel: true` = assinou no painel) · `all_signed` ·
 `sealed` (documento final gerado, `sealed_sha256`) · `refused` · `cancelled` · `expired` · `delivery_failed`
-(motivo em `delivery.failed[]`) · `reminded` · `resent`. Tudo append-only — é o relatório de evidências.
+(motivo em `delivery.failed[]`) · `reminded` · `resent` · `copy_sent` / `copy_failed` (a via assinada de cada pessoa,
+estado em `delivery.copies[]`). Tudo append-only — é o relatório de evidências. `delivery.failed[]` também mostra a
+recusa que a Meta manda depois (caixa oficial fora da janela de 24 h, motivo `window_expired`) e some sozinha se a
+mensagem acabar entregue.
+
+Falhas de e-mail (16/10): o convite e a via por e-mail tentam de novo sozinhos (1, 5 e 15 min). Só se nada der certo
+aparece `envio_falhou` (o servidor de e-mail não respondeu); `email_recusado` (o servidor de e-mail recusou o envio)
+aparece na hora. Falha de convite antigo some se a pessoa abriu o link, pediu o código ou assinou depois. Contrato em
+`signed_pending_seal` = o documento final está sendo gerado, com novas tentativas automáticas por até ~42 min; só um
+`seal_failed` depois disso quer dizer que não deu (oriente falar com o suporte).
+
+## A via assinada (15/10)
+Quando o documento final fica pronto, cada pessoa que assinou pelo link (testemunhas incluídas) recebe a sua via em PDF
+pelo mesmo canal do link: anexada numa mensagem na conversa dela (WhatsApp) ou no e-mail (acima de 10 MB vai sem anexo,
+pedindo que peça a via a quem enviou). Quem assinou no painel não recebe. Não há ferramenta para mandar de novo: oriente
+baixar na tela do documento. O código de 6 dígitos de quem assina por e-mail chega no próprio e-mail.
 
 ## Como mandar um contrato (receita)
 1. `lionchat_signature_documents_list` → escolha o modelo (ou crie um `text` com `signature_documents_create`;
@@ -59,7 +74,9 @@ Participante: `pending` → `viewed` → `verified` (confirmou o código) → `s
   Passou disso o envio/prévia volta `422 fila_cheia` — é só repetir em instantes (o modelo está bom).
 - **Limite mensal** (`signature_envelopes_limits`): cada contrato criado consome 1 vaga; cancelar não devolve.
 - **PDFs** (original, assinado, evidências) e o **QR de conferência** só existem pela tela/download autenticado —
-  não há ferramenta que devolva os bytes. O `sealed_sha256` é o hash do documento final.
+  não há ferramenta que devolva os bytes. O `sealed_sha256` é o hash do documento final. Exceção desde 15/10: a via
+  assinada vira anexo da mensagem na conversa de quem assinou por WhatsApp, então aparece nas ferramentas de mensagens
+  da conversa (`conversations_messages_*`).
 - **Só pela tela, de propósito** (existem na API, mas NÃO como ferramenta): importar um Word (`import_docx`),
   pré-visualizar modelo ou rascunho (`preview`, `preview_draft`) e baixar PDF (`download`). O conector não envia
   arquivo nem recebe PDF — não prometa "vou gerar a prévia" ou "vou baixar o assinado"; oriente a tela.

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

@@ -418,6 +418,9 @@ Nas condições de automação, desambigue com `custom_attribute_type`:
 
 Sem o tipo, o filtro pode bater no escopo errado. A UI mostra sufixo "(Conversa)/(Contato)".
 
+Campo personalizado da EMPRESA do contato (desde 2026-10-16): `"custom_attribute_type": "company_attribute"`
+(a chave pode ser igual a de contato; o tipo decide). Na tela aparece no grupo "Atributos da empresa".
+
 ## Meta Lead e CAPI (2026-06)
 
 - Conexão Meta Lead agora é **por página selecionada** (a BM virou só rótulo — antes puxava todas
@@ -592,7 +595,8 @@ e o `{{meet_link}}` da mensagem de confirmação do Booking passaram a vir preen
 vazios) — isso vale inclusive para cliente que não usa IA.
 
 **3. A IA não confirma reunião que não existe.** No último instante antes da resposta virar
-mensagem: se ela afirma agendamento concluído, a agenda está liberada e não há compromisso real na
+mensagem: se ela afirma agendamento concluído, a agenda está liberada (a conta tem tipo de agendamento E o
+agente tem ao menos uma das 4 ferramentas de agenda ligada — desde 14/10) e não há compromisso real na
 conversa, o sistema roda UMA tentativa guiada que agenda de verdade com a data/hora prometidas.
 Agendou, sai a confirmação verdadeira; não agendou, a frase é trocada por uma honesta — nunca
 silêncio. Diagnóstico: se o cliente disser "a IA confirmou e não tem nada na agenda", esse é o
@@ -729,6 +733,8 @@ Fontes/campos disponíveis (`source` / `field`):
 | Equipe | conversation | team.name |
 | Nome da conta | account | name |
 | Campo personalizado | contact | custom_attributes.CHAVE |
+| Campo personalizado da EMPRESA do contato (2026-10-16) | company | custom_attribute.CHAVE |
+| Razão social / CNPJ / telefone / e-mail / cidade / estado da empresa | variable | contact.company.legal_name (ou .cnpj, .phone, .email, .address.city, .address.state) |
 
 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).

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

@@ -278,6 +278,12 @@ responsável, chame `conversations_update` depois — não adianta mandar junto
 **O que É aproveitado:** `custom_attributes` entram por merge, **sem sobrescrever chave que já tem
 valor**. A conversa mantém a origem com que nasceu e só ganha o que ainda não tinha.
 
+**Conversa NOVA nasce com a origem da ficha (16/10/2026).** Quando você (API, automação, fluxo ou
+formulário) cria uma conversa nova e a ficha do contato já traz sinal de anúncio (formulário da Meta, UTM,
+Google, LionTrack), a conversa já nasce com os `origin_*` preenchidos — antes ficava sem origem até o
+cliente escrever. Sem sinal na ficha, nasce sem origem (nunca "Direto"): quem classifica "Direto" é a
+primeira mensagem do cliente. Origem que você mandar na criação não é trocada.
+
 **Reuso não dispara `conversation_created`** — automação, gatilho de flow, webhook de saída,
 notificação e a Agenda não rodam. Se o seu fluxo depende de um desses, ele não vai acontecer
 quando houver reuso.
@@ -621,7 +627,7 @@ O conector **liga a condicao com a SEGUINTE**. Logo:
 | `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` |
+| `custom_attribute_type` | so p/ atributo personalizado | `conversation_attribute`, `contact_attribute` ou `company_attribute` (campo personalizado da EMPRESA do contato, desde 2026-10-16: so atributo personalizado, negativo inclui contato sem empresa, `attribute_changed` recusado, modulo Empresas desligado = nunca casa) |
 
 ### Operadores de filtro
 
@@ -715,16 +721,18 @@ Todos os formatos abaixo foram conferidos linha a linha em `app/services/action_
 | `snooze_conversation` | `[]` |
 | `resolve_conversation` / `open_conversation` / `pending_conversation` | `[]` |
 | `update_contact_attribute` / `update_conversation_attribute` | `[{"attribute_key": "chave", "value": "texto ou {{contact.phone_number}}"}]` — chave PROTEGIDA é recusada na execução e fica só no log (10/09/2026): prefixos `waha_whatsapp_`, `whatsapp_`, `origin_`, `ctwa_`, `meta_lead_`, `lt_` e atributos de sistema como `utm_*`/`gclid`. Vale pra macro e automação |
-| `create_kanban_item` | `[{"funnel_id": 31, "funnel_stage": "prospeccao", "allow_duplicates": false}]` |
+| `create_kanban_item` | `[{"funnel_id": 31, "funnel_stage": "prospeccao", "allow_duplicates": false}]` — sem `allow_duplicates`, duas execuções no mesmo instante (formulário + conversa que ele criou) NÃO criam dois cards (09/10/2026), e o texto `"false"` vale como desmarcado. Card ADIADO no funil conta como card que já existe: não cria outro, move se a etapa for diferente e continua adiado (11/10/2026) |
 | `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 |
+| `set_kanban_item_status` | `[{"funnel_id": 31, "status": "won"}]` — `won`, `lost` ou `open`. Status fora disso e ignorado. `open` num card ADIADO abre o card na hora e dispara "Card aberto" (11/10/2026) |
+| `snooze_kanban_item` | `[{"funnel_id": 31, "amount": 3, "unit": "days"}]` — ADIA o card por N horas (`hours`) ou dias (`days`); minimo 1 hora, so card aberto (11/10/2026). Em regra de evento de CARD (`kanban_item_*`) o card e o do evento: `[{"amount": 3, "unit": "days"}]`. Diferente das outras acoes de card, sem card no funil, card ganho/perdido ou tempo invalido = FALHA visivel no historico da regra, nunca pula calado. Ver "Card adiado" no kanban-deep-dive |
 | `start_kanban_item_timer` / `stop_kanban_item_timer` | `[{"funnel_id": 31}]` |
 | `wait` | `[30]` — segundos. Com conferência na volta: `[{"seconds": 120, "only_if_open": true, "only_if_no_reply": true}]`. Ver "Acao Aguardar" abaixo |
 
 **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.
+a acao e pulada (fica so no log do servidor) — exceto `snooze_kanban_item`, que FALHA visivel. Use
+`create_kanban_item` antes, na mesma regra.
 
 ### Acao `wait` (Aguardar) — novo 2026-08-04
 

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

@@ -154,6 +154,9 @@ Company
 ├── contacts_count
 ├── avatar (foto)
 ├── additional_attributes (jsonb: legal_name, cnpj, phone, email, address{...}, social_profiles{...}; 2026-09-25)
+├── custom_attributes (jsonb: atributos personalizados de EMPRESA, definicoes attribute_model=company_attribute;
+│   2026-10-15. Gravar: lionchat_companies_update com custom_attributes {chave: valor}; MESCLA; null limpa a chave;
+│   so chave definida como atributo de empresa da conta; criar a definicao exige o modulo Empresas)
 └── last_activity_at (ultima vez que um contato da empresa teve atividade; 2026-09-25)
 
 AttributeChange (histórico de alterações de atributo — 2026-09-11)
@@ -206,6 +209,56 @@ atendente). Cadastro da empresa (25/09): `lionchat_companies_create`/`_update` a
 valor vazio apaga aquela chave. Excluir empresa: so administrador; os contatos ficam, so deixam de estar na empresa (as anotacoes da
 empresa vao junto).
 
+**Atributos personalizados da EMPRESA (2026-10-15):** campos proprios da empresa que o cliente cria ("Segmento",
+"Data de fundacao", "Faturamento anual"...), na aba Empresa de Configuracoes > Atributos personalizados. Sao um
+quarto tipo de definicao, separado de conversa, contato e variavel de conta:
+- **Criar a definicao:** `lionchat_custom_attributes_create` com `attribute_model: "company_attribute"` (SEMPRE com o
+  sufixo). So na conta com o modulo Empresas ligado (sem ele: 422 "O modulo Empresas nao esta ligado nesta conta").
+  Tipo `secret` e recusado. Chaves reservadas (os campos proprios da empresa) sao recusadas: `name`, `domain`,
+  `description`, `legal_name`, `cnpj`, `phone`, `email`, `address`, `social_profiles`, `contacts_count`,
+  `created_at`, `last_activity_at`. As mesmas regras valem ao TROCAR o `attribute_model` de uma definicao existente.
+- **Listar:** `lionchat_custom_attributes_list` com `attribute_model=company_attribute`.
+- **Preencher:** `lionchat_companies_update` (ou `_create`) com `custom_attributes: {"segmento": "Varejo"}` dentro do
+  wrapper `company`. MESCLA: mande so o que muda; `null` ou texto vazio LIMPA a chave; chave nao mandada fica.
+  Valores SIMPLES (texto, numero, verdadeiro/falso ou null) — lista ou objeto dentro = 422. Teto de 1.500 caracteres
+  por valor. Data pode ir como `15/10/2020` (grava `2020-10-15`).
+- **So aceita chave que JA existe** como atributo de empresa da conta: chave desconhecida = 422 com a lista das
+  validas, e NADA do pedido e gravado (nem o nome nem o cadastro que vieram junto). Crie a definicao antes de
+  preencher — a lista e lida na hora, entao criar e preencher logo em seguida funciona.
+- **Ler:** `lionchat_companies_show`/`_list` trazem `custom_attributes` em cada empresa (`{}` quando vazio).
+- **Onde mais ele aparece (2026-10-16), igual aos atributos de contato.** A empresa e a do CONTATO: um contato
+  tem no maximo UMA empresa (`contacts.company_id`); a conversa nao tem empresa propria. Com o modulo Empresas ligado:
+  - **Variavel** em mensagem, resposta pronta, automacao, fluxo, campanha e mensagem agendada:
+    `{{contact.company.custom_attribute.<chave>}}` (data sai DD/MM/AAAA) e o cadastro `{{contact.company.name}}`,
+    `{{contact.company.legal_name}}`, `{{contact.company.cnpj}}` (so digitos), `{{contact.company.phone}}`,
+    `{{contact.company.email}}`, `{{contact.company.address.city}}`, `{{contact.company.address.state}}`.
+    `{{contact.company}}` sozinho imprime o nome. Contato sem empresa = vazio, sem erro.
+  - **Modelo oficial do WhatsApp** (`variable_mapping`): campo personalizado com
+    `{"source": "company", "field": "custom_attribute.<chave>"}`; cadastro com
+    `{"source": "variable", "field": "contact.company.cnpj"}` (tambem `legal_name`, `phone`, `email`,
+    `address.city`, `address.state`). O nome da empresa ja e `contact.company_name`.
+  - **Condicao do bloco Condicao do fluxo:** regra `{"valueType": "attr_config", "attrSource": "company",
+    "attr_key": "<chave>", "operator": "...", "value": "", "values": [...]}`. `attr_key` = chave personalizada OU
+    cadastro com prefixo: `company.name`, `company.legal_name`, `company.cnpj` (comparado por digitos),
+    `company.phone`, `company.email`, `company.address.city`, `company.address.state`. Contato sem empresa = valor
+    vazio (os negativos casam).
+  - **Condicao de automacao e filtro da lista de contatos** (`lionchat_contacts_filter`, segmento salvo, acao em
+    massa): `{"attribute_key": "<chave>", "filter_operator": "...", "values": [...],
+    "custom_attribute_type": "company_attribute"}`. So atributo PERSONALIZADO (o cadastro da empresa fica fora).
+    Operadores pelo tipo do atributo: todos aceitam `equal_to`/`not_equal_to`/`is_present`/`is_not_present`;
+    texto tambem `contains`/`does_not_contain`; numero, data e hora tambem `is_greater_than`/`is_less_than`.
+    Negativo inclui o contato SEM empresa. `attribute_changed` e recusado (a empresa nao dispara evento).
+    Chave igual a de um atributo de contato e permitida: quem decide e o `custom_attribute_type`.
+  - **Filtro de CONVERSAS** (`lionchat_conversations_filter`) com `company_attribute` = 422 ("Atributo de empresa
+    so filtra a lista de contatos").
+  - **IA:** o Agente de IA e o Copiloto veem o nome, o cadastro e os campos personalizados preenchidos da empresa do
+    contato. Somente leitura: a IA nao grava na empresa.
+  - **Modulo Empresas DESLIGADO = para tudo:** variavel sai vazia, condicao nunca casa (nem "diferente de" nem
+    "esta vazio"), filtro nao acha ninguem, a IA nao ve a empresa. O que foi preenchido fica guardado.
+  - **Ainda NAO:** condicao de SAIDA do fluxo, gatilho do fluxo, parametro de ferramenta de IA, acao "Alterar
+    atributo" do fluxo/automacao (nao grava na empresa), exportacao/relatorio, historico de alteracoes e gatilho
+    de data.
+
 **Dados cadastrais (`additional_attributes.cadastral`):** CPF, CNPJ, RG, passaporte, nascimento,
 gênero, estado civil, profissão e endereço completo moram em `additional_attributes->cadastral`.
 São **IMUTÁVEIS por padrão** (primeira escrita vale) — alterar exige `force_update: true`, que SÓ
@@ -282,6 +335,16 @@ KanbanItem
 ├── activities (jsonb)
 ├── timer_started_at / timer_duration
 └── created_at
+    (item_details.status guarda open/won/lost; ADIADO = open + linha em kanban_item_snoozes — a resposta da API
+     traz effective_status open|snoozed|won|lost e snoozed_until, calculados; nao sao colunas)
+    (13/10/2026: item_details.attributed_to = vendedor do ganho; item_details.co_attributed_to = CO-PARTICIPANTE da
+     venda, ex. o SDR — so em card ganho, id de agente; co_attributed_name o card preenche. Ver kanban-deep-dive)
+
+KanbanItemSnooze (kanban_item_snoozes — 11/10/2026: ate quando o card esta ADIADO; uma linha por card)
+├── account_id, kanban_item_id (unico)
+├── snoozed_until (datetime)
+├── snoozed_by_id (quem adiou; nulo = automacao, macro ou fluxo)
+└── created_at / updated_at
 
 Item do checklist (elemento do array jsonb `checklist`)
 ├── id (uuid string)
@@ -485,7 +548,9 @@ db/schema.rb, tabela booking_event_types)
 │   {{nome}} {{email}} {{telefone}} {{data}} {{horario}} {{dia_semana}} (NOVO 24/08 — dia por
 │   extenso em pt: "terça-feira"; irmã do {{booking.weekday}} do FlowBuilder, mesma grafia)
 │   {{tipo_evento}} {{titulo}} {{duracao}} {{agente}} {{descricao}} {{meet_link}}
-│   {{link_cancelar}} {{link_remarcar}} {{horas_ate_evento}} {{horas_desde_evento}}
+│   {{link_cancelar}} {{link_remarcar}} {{link_confirmar}} {{link_salvar_na_agenda}} (16/10: abre a
+│   página onde o cliente salva no Google Agenda ou na agenda do iPhone/Outlook)
+│   {{horas_ate_evento}} {{horas_desde_evento}}. Data, hora e duração saem do COMPROMISSO da Agenda (16/10)
 └── booking_availabilities (has_many — dias/horários; `booking_availabilities_attributes` no create)
 
 Booking (agendamento confirmado — tabela bookings)
@@ -770,6 +835,16 @@ LeadFormResponse (um preenchimento do formulário)
 └── answers (respostas) / milestones (marcos atingidos) / utm_params / started_at / completed_at /
     abandoned_at
 
+WhatsappForm (Formulário do WhatsApp — formulário nativo da Meta, 17/10/2026; mesma liberação dos Formulários)
+├── account_id (FK) / inbox_id (caixa oficial usada para a credencial) / waba_id (conta do WhatsApp)
+├── name (único na conta do WhatsApp) / status (draft/publishing/published/deprecated) / meta_flow_id (número na
+│   Meta — vai no botão FLOW do modelo) / meta_status / last_error / published_at
+├── editor_data (jsonb: telas e campos, códigos f_<n> e o_<n>) / save_targets (jsonb: "Salvar em" por código)
+├── images (arquivos anexados; o campo de imagem guarda o blob_id)
+└── publications (has_many: uma por publicação — number, token, editor_data e flow_json da época)
+    → a resposta do cliente vira MENSAGEM entrante content_type form (items + submitted_values +
+      whatsapp_form), com foto/arquivo como anexos
+
 CustomWebhookIntegration (Webhook Universal — entrada)
 ├── account_id (FK)
 ├── name / token (URL única) / active
@@ -914,3 +989,46 @@ SignatureDocument (modelo)  1 ──── N  SignatureEnvelope (contrato de UMA
 - `roles_layout` é jsonb aberto e MESCLADO no update; `progress` é calculado (aguardando/visualizado/assinado/encerrado).
 - Feature por conta: `document_signing`. Limite mensal em `usage_limits.signature_requests_per_month` (0 = ilimitado).
 - Detalhe completo: resource `lionchat://docs/assinatura-eletronica`.
+
+## Categorias dos atributos personalizados (17/10/2026)
+
+Pastas que abrem e fecham para organizar os atributos de cada aba de Configuracoes > Atributos personalizados (estilo
+"Data fields" do Pipedrive). Aparecem tambem onde a equipe preenche: painel lateral da conversa (atributos da conversa
+e do contato, grupos que abrem e fecham por pessoa), ficha do contato, pagina da empresa e bloco "Dados Adicionais"
+do card.
+
+- **Opcional:** conta sem categoria ve tudo como antes. Atributo que nao esta em nenhuma categoria aparece em "Sem
+  categoria" (primeiro grupo da tela).
+- **Uma aba por categoria** (`attribute_model`): `conversation_attribute`, `contact_attribute`, `company_attribute`
+  (so com o modulo Empresas) ou `kanban_item_attribute` (aba Card). Variavel de conta nao tem categoria. O mesmo nome
+  pode existir em abas diferentes.
+- **Um atributo em UMA categoria so.** Colocar numa nova tira da anterior; ele entra no fim da categoria.
+- **Chave do Card:** os campos do Card vivem em `global_custom_attributes` da configuracao do Kanban
+  (`lionchat_kanban_config_list`) e sao identificados pelo `name` EXATO (maiusculas e espacos). Nunca use uma chave
+  "em minuscula com sublinhado" derivada do nome: o servidor recusa (`unknown_attribute`).
+- **Regras do nome:** 1 a 60 caracteres, sem repetir na aba (sem diferenciar maiuscula), "Sem categoria" reservado,
+  ate 50 categorias por aba.
+- **Excluir categoria nunca apaga atributo nem valor:** os atributos voltam para "Sem categoria".
+- **Atributo apagado:** o vinculo fica guardado sem efeito. Se o atributo for recriado PELA API com a mesma chave, ele
+  volta para a categoria; pela tela, vale a categoria escolhida no formulario.
+- Escrita so de administrador (401 para os demais); leitura para todos.
+
+Ferramentas:
+
+| Tool | Para que |
+|---|---|
+| `lionchat_custom_attribute_categories_list` | Todas as categorias da conta (`id, attribute_model, name, position, attribute_keys`) |
+| `lionchat_custom_attribute_categories_create` | Cria na aba (`name`, `attribute_model`); entra no fim |
+| `lionchat_custom_attribute_categories_update` | Renomeia (`name`); a aba nao muda |
+| `lionchat_custom_attribute_categories_destroy` | Exclui (atributos voltam para "Sem categoria") |
+| `lionchat_custom_attribute_categories_reorder` | Nova ordem da aba: `ids` com TODOS os ids da aba (faltou/sobrou = 422; releia e mande de novo) |
+| `lionchat_custom_attribute_categories_assign` | Coloca (`category_id`) ou tira (`category_id` nulo) um atributo |
+
+Receita "organizar os atributos de contato do cliente": `lionchat_custom_attributes_list` (`attribute_model:
+contact_attribute`) para ver as chaves -> `lionchat_custom_attribute_categories_create` para cada grupo -> um
+`lionchat_custom_attribute_categories_assign` por atributo. Para criar um atributo ja dentro de uma categoria:
+`lionchat_custom_attributes_create` e depois `assign` com a `attribute_key` DEVOLVIDA pelo create (o servidor
+normaliza a chave: sem acento, minuscula).
+
+FUTURO (ainda nao existe): usar a categoria como filtro (ex.: um funil mostrar so certas categorias). Nao prometa isso
+ao cliente.

package/dist/docs/resources/filtros-e-relatorios.md

@@ -35,6 +35,8 @@ E/OU é encadeado condição a condição (sem parênteses).
 
 Atributo personalizado: informe `custom_attribute_type` na condição — `'conversation_attribute'`
 (atributo da conversa) ou `'contact_attribute'`. Sem ele o escopo pode sair errado.
+`'company_attribute'` (atributo da empresa) NÃO vale em conversas: 422 (desde 16/10/2026; use o filtro de
+CONTATOS).
 
 **`contact_attribute` lê a FICHA DO CONTATO da conversa (funciona de verdade desde 24/09/2026).** Antes o
 servidor ignorava o valor e lia o atributo da própria conversa — por isso lead de formulário da Meta
@@ -102,6 +104,11 @@ Mesmo shape de condição. 15/página.
 - `card_funnel_id`, `card_stage`, `card_priority`, `card_status` (equal_to/not_equal_to) — card
   do Kanban vinculado.
 - Condição com `custom_attribute_type:'conversation_attribute'` — atributo da conversa vinculada.
+- Condição com `custom_attribute_type:'company_attribute'` (16/10/2026) — campo PERSONALIZADO da empresa do
+  contato, ex. `{attribute_key:'segmento', filter_operator:'equal_to', values:['Varejo'],
+  custom_attribute_type:'company_attribute'}`. Operadores pelo tipo (texto: igual/diferente/contém/não contém/
+  preenchido; número/data/hora: + maior/menor). Negativo inclui contato SEM empresa. Módulo Empresas desligado =
+  ninguém. Chave que não existe como atributo de empresa = 422.
 
 ### Duas regras que enganam nos filtros
 
@@ -119,7 +126,8 @@ GET com parâmetros FLAT (não usa payload). Filtros REAIS (2026-07-24 — parâ
 stage_id/inbox_id/sort_by/sort_direction/page foram REMOVIDOS, eram ignorados pelo backend):
 
 - `funnel_id` (obrigatório), `stages[]` (chaves internas das etapas), `priorities[]`,
-  `statuses[]` (open/won/lost), `agent_id`, `value_min`/`value_max`
+  `statuses[]` (open/won/lost/snoozed — desde 11/10/2026 `open` = aberto e NÃO adiado e `snoozed` = adiado; ver
+  "Card adiado" no kanban-deep-dive), `agent_id`, `value_min`/`value_max`
 - `date_start`/`date_end` (criação do card, YYYY-MM-DD)
 - `stage_date_start`/`stage_date_end` (2026-08-07) — **quando o card ENTROU na etapa em que ele está
   agora** (`stage_entered_at`, caindo em `created_at` para card que nunca se moveu). NÃO confundir com
@@ -158,9 +166,30 @@ NÃO há filtro por time aqui (por time: use o relatório agregado abaixo, ou fi
 
 `GET /kanban_items/reports` — a resposta é um OBJETO de métricas (não lista): valores GANHOS,
 contagem/valor por etapa, forecast ponderado, top negócios, cards parados, metas do funil.
-Params: `funnel_id` (obrigatório), `from`, `to`, `user_ids[]` (agentes), `team_id`, `date_basis`.
+Params: `funnel_id` (obrigatório), `from`, `to`, `user_ids[]` (agentes), `team_id`, `date_basis`,
+`label_names[]` (só cards com essas etiquetas — nome da etiqueta, como aparece na conversa; desde 02/10/2026),
+`win_reason_ids[]` (só ganhos com esses motivos — o código do motivo em `lionchat_kanban_config_list`; desde 02/10/2026)
+e `include_shared_sales` (true = traz o quadro "sozinho x compartilhadas", ver abaixo; 13/10/2026).
 É a ferramenta certa pra "relatório de vendas/ganhos do mês por agente ou time".
 
+**Co-participante da venda (13/10/2026).** No ganho dá para marcar, além do vendedor, UM co-participante (ex.: o SDR
+que trouxe a venda — ver `lionchat://docs/kanban-deep-dive`, seção "Co-participante da venda"). O relatório mostra isso
+SEM mudar nenhum número antigo (Ganhos e Receita continuam do vendedor):
+- `coParticipantRanking` (sempre vem): `[{id, name, sales, value}]`, uma linha por co-participante, contando cards
+  GANHOS no período com os mesmos recortes de funil, régua, etiqueta e motivo. O filtro de pessoa/time vale sobre o
+  co-participante. Co-participante igual ao vendedor não conta. Lista vazia = a conta não usa o recurso.
+- Com `include_shared_sales=true`: `sharedSalesSummary` `{solo, shared, sharedSellerLeft}` (cada um `{count, value}`; sozinho + compartilhadas = ganhos do período; `sharedSellerLeft` = compartilhadas cujo vendedor saiu da conta)
+  e `sharedSalesBySeller` `[{id, sales, value}]` (parte compartilhada de cada vendedor). Sem o parâmetro a resposta é
+  a de sempre. Venda compartilhada = ganha no período com co-participante DIFERENTE do vendedor gravado no card; sair da
+  conta NÃO transforma venda compartilhada em individual.
+- **A lista das vendas compartilhadas** (data, negócio, valor, vendedor, co-participante) é a tool
+  `lionchat_kanban_items_shared_sales` (`GET /kanban_items/shared_sales`): mesmos filtros (`funnel_id` opcional, `from`,
+  `to`, `date_basis`, `user_ids[]`, `team_id`, `label_names[]`, `win_reason_ids[]`), a mais recente no topo, 50 por vez
+  (`limit` até 500). Para a página seguinte, devolva o `nextCursor` recebido em `cursor_at` e `cursor_id`; `nextCursor`
+  nulo = acabou. Com filtro de pessoa/time só entra venda em que alguém do filtro foi VENDEDOR ou CO-PARTICIPANTE, e vêm
+  `asSellerCount`/`asCoCount` (sem filtro, nulos). `canOpen` por linha diz se quem pediu pode abrir o card; quem vê só
+  parte do Kanban recebe as vendas que não vê como `hiddenCount` (nunca o título).
+
 **`date_basis` (2026-08-07) — qual data o período considera.** A resposta devolve a régua aplicada em
 `dateBasis`; valor inválido cai no padrão sem erro.