Skip to main content
O template do projeto é um JSON com o projeto inteiro. É o que get_template devolve e o que update_template aceita, em qualquer subconjunto de blocos. Esta página lista todos os blocos: o que cada um é, como cada item é reconhecido numa escrita e o que a escrita faz de diferente nele. As regras que valem para todos os blocos (lista inteira, órfãos, campo vazio, ligar e desligar, referências por nome) estão em Como uma escrita funciona.

Visão geral

“slug (ou nome)”: casa pelo slug quando o item traz um; sem slug, pelo nome. Só os blocos com slug renomeiam.

Os blocos

version

A versão do formato, hoje "1.0". Obrigatória no arquivo completo; num envio parcial pelo MCP, não precisa vir.

meta

O nome e a descrição do projeto, e o horário em que o agente atende. icon viaja, mas não é gravado. Na escrita: trocar meta.name renomeia o projeto. A partir daí, o MCP exige o nome novo no par project_id + project_name. active_schedule é o horário de funcionamento do agente: fora das janelas, a IA não responde. null deixa o agente sempre ligado; campo ausente não mexe. Pergunte antes de mudar: muda quando clientes reais são atendidos.

llm_attendant

Os ajustes do agente que ficam no projeto, fora do config. Valem para os dois motores: buffer (segundos), pausa humana (minutos), segmentação e voz (ElevenLabs). Os demais campos (prompt, modelo, temperatura, mídia, busca na web) são do motor antigo; no LangChain Agent, isso fica no bloco langchain. Na escrita:
  • functions viaja na leitura e é ignorada na escrita: carrega endereços e alvos do motor antigo. Se a lista enviada for diferente da atual, uma nota avisa.
  • O motor (llm) não muda por aqui. Migrar é pelo painel.
  • Campo null, omitido ou vazio não grava, inclusive api_key e eleven_labs_api_key. Um texto de exemplo no lugar da chave grava por cima: omita o campo ou devolva o valor lido.

tags

As tags do projeto, com cor, descrição e vínculo (contato ou conversa). Na escrita: renomeia pelo slug. Cor obrigatória, no formato #RRGGBB.

columns

As colunas do funil, na ordem, com as três chaves de comportamento. Na escrita: renomeia pelo slug. order é obrigatório. A coluna com order 0 é a de entrada: recebe leads novos e é para onde o lead volta ao encerrar o atendimento.

properties

As propriedades personalizadas, de quatro tipos: texto livre (TEXT), número (NUMBER), lista fechada (ENUM) e lista fechada com um número por opção (FLOAT_ENUM, que as métricas do funil somam). Na escrita:
  • O tipo vai em property_type. Ausente, não mexe no tipo de uma propriedade que já existe; numa propriedade nova, vale TEXT. O campo antigo is_enum: true ainda funciona e equivale a ENUM. Com property_type ENUM ou FLOAT_ENUM, não precisa mandar is_enum.
  • Lista fechada (ENUM, FLOAT_ENUM) precisa de values com ao menos um valor, sem repetidos (maiúsculas não contam). values numa propriedade que não é de lista é ignorado, com nota.
  • Em FLOAT_ENUM, cada opção tem numeric_value (obrigatório) e o value é um slug: só a-z, 0-9, _ e - (ex.: plano_anual). É esse slug que o agente e a API gravam no lead; o texto que a tela mostra vai em description.
  • Troca de tipo de uma propriedade já preenchida em algum contato não é feita, com nota e a contagem de contatos. A exceção é ENUM ⇄ FLOAT_ENUM, sempre permitida (o valor gravado no lead é o mesmo).
  • ENUM → FLOAT_ENUM: opções que já existiam e não vieram com numeric_value ficam sem número e não entram nas métricas, com nota. FLOAT_ENUM → ENUM apaga o numeric_value das opções e volta o formato para NONE.
  • display_format: CURRENCY_BRL mostra o número como moeda (R$) e só vale em NUMBER e FLOAT_ENUM; nos outros tipos é ignorado, com nota. Ausente, não mexe no formato.
  • Valor retirado de values continua existindo: pode haver lead preenchido com ele.
  • send_to_ai decide se o valor entra no contexto do agente. Padrão: true (propriedade criada pelo painel vai para a IA). Não aparece no formulário do painel; só se altera pelo template.

kanban_column_metrics

As métricas por coluna do funil: soma e contagens que aparecem no topo de cada coluna (Funil). Na escrita:
  • A coluna vai por nome (column_name), a propriedade pelo slug e a tag pelo nome. Coluna, propriedade ou tag que não existem no projeto: a métrica é ignorada, com nota.
  • threshold_operator: "gt" (maior que) ou "lt" (menor que). Ausente vale "gt". Só em COUNT_THRESHOLD, junto com threshold_value.
  • COUNT_EQ só com propriedade ENUM, e eq_value precisa ser um dos value dela. Senão, a métrica é ignorada, com nota.
  • Campo que não pertence ao tipo (tag em SUM, limite em COUNT_TAG, operador em COUNT_EQ…) torna o template inválido.
  • A métrica não tem nome nem slug: é identificada pela combinação coluna + tipo + propriedade ou tag + limite e operador (ou valor). Trocar o limite, o operador ou o valor cria outra métrica; a antiga continua.
  • Métrica que não vem no JSON não é apagada. Ela volta em orphans. Para tirar uma métrica, use o painel.
  • display_order define a ordem na coluna. Ausente, não mexe.

skills

As skills do agente: conhecimento carregado só quando o agente precisa. Na escrita: grava a skill no projeto e, se o projeto está no LangChain Agent, acrescenta ao config do agente as skills que ele ainda não tem (cria uma versão não publicada). Uma skill que o agente já tem não é sobrescrita: para mudar o texto dela, altere a tool skill no bloco langchain. Skill sem conteúdo não entra, com nota.

follow_ups

Follow-ups (template da Meta depois de um tempo) e reengajamentos (texto livre antes de a janela de 24h fechar), no mesmo bloco, diferenciados por method. Na escrita:
  • Nasce desligado se status não vier.
  • O template da Meta vai por nome (template_name). Se ele ainda não existe sincronizado no projeto, o follow-up entra sem template e guarda o nome; uma nota avisa, e o vínculo é feito quando o template for sincronizado.
  • Em RE_ENGAGEMENT, delay são os minutos antes de a janela fechar, e a unidade é sempre minutos.
  • Colunas e tags inexistentes são retiradas dos filtros, com nota.
  • Item sem name é ignorado.

webhooks

Webhooks de eventos: a Zatten avisa um sistema externo quando algo acontece (lead criado, conversa, kanban, tags, erros). Na escrita: nasce desligado (e sem endereço, se url não vier). Só liga com endereço. url vazia não grava; preenchida troca o endereço do cliente. Item sem name é ignorado.

integration_webhooks

Webhooks por inatividade: enviam os dados do lead para um sistema externo depois de um tempo sem interação. Na escrita: mesmas regras de endereço e estado do webhooks. Colunas e tags inexistentes são retiradas dos filtros, com nota.

mcps

Servidores MCP cadastrados no projeto para o motor antigo. No LangChain Agent, os servidores MCP ficam como tools no bloco langchain. Na escrita: nasce desligado (e sem endereço, se url não vier). Só liga com endereço. url e headers vazios não gravam. Mantenha request_approval desligado.

conversions

Eventos enviados ao Meta Ads quando um lead que veio de anúncio entra numa coluna. Na escrita: nasce desligada. A coluna vai por nome (column_name); se não existir, a conversão é ignorada, com nota.

unseen_message

A resposta automática para mensagens que chegam por anúncio e não aparecem no CRM (conexão com coexistência). Existe no máximo uma por projeto. Na escrita: a chave é fixa. Mandar outro name renomeia a mesma resposta. Nasce desligada.

attendant_teams

Os departamentos do projeto. Na escrita: renomeia pelo slug. Os membros não viajam: departamento criado nasce vazio, e alguém adiciona as pessoas no painel.

meta_templates

Os templates da Meta do projeto. get_template traz todos. Na escrita pelo MCP: nada é criado nem alterado. Template existente nunca é atualizado (o estado é da Meta). Template que falta não é enviado à Meta: a nota lista quais faltam e sugere submit_meta_templates: true, opção que o MCP não tem. O envio é feito por uma pessoa, no painel.

zapster_templates

Os modelos de mensagem da API não oficial do WhatsApp (Zapster): o texto que o agente ou uma automação envia, com variáveis. Na escrita: cria o que falta e atualiza o que existe, casando pelo name (único no projeto). Entra antes do bloco langchain, então um agente que aponta para o modelo pelo nome já o encontra na mesma escrita.

inactivity_handovers

Transbordos por inatividade: depois de um tempo sem interação, o lead vai para uma coluna de atendimento humano, com mensagem dentro e fora do horário comercial. Na escrita: nasce desligado. A coluna de destino vai por nome; se não existir, o transbordo é ignorado, com nota. Colunas e tags de origem inexistentes são retiradas, com nota.

custom_actions

Ações personalizadas: botões no lead que fazem uma chamada HTTP quando um humano clica. Na escrita: sem webhook_url, nasce pendente: sem endereço e desligada. O estado é is_active (boolean). Só liga com endereço. webhook_url, headers, query_params e body_params vazios não gravam.

quick_messages

Mensagens rápidas: blocos de texto e mídia que o humano envia com /comando. Na escrita: nasce desligada se is_active não vier. O comando é gravado sem barra, em minúsculas e com hífens no lugar de espaços. O filtro por departamento viaja pelo nome do departamento, em department_names: lista vazia vale para todos, campo ausente não mexe. Departamento que não existe no projeto fica de fora, com nota.

flows

Os fluxos do Trigger Flow: gatilho, condições e ações, desenhados no editor. Na escrita:
  • Fluxo novo é criado desligado (se status não vier). Referências a coluna, tag e departamento dentro do grafo vão por nome; se alguma não existir, o fluxo não é criado, com nota.
  • Fluxo que já existe (mesmo nome) não tem o grafo reescrito: só o status muda. O desenho é do editor.
  • Responsável não viaja: é uma pessoa, não configuração.
  • Não mande execution_plan; ele é refeito a partir dos nós.
  • Fluxo sem nó de gatilho não é criado. Dois fluxos com o mesmo caminho de webhook de entrada também não.
  • Gatilhos em breve (lead.message_received, lead.property_changed, lead.inactive) não rodam hoje, nem pela API. Não monte fluxos com eles. lead.created (Novo lead criado) está disponível; ele não roda para leads importados por CSV (ver quando dispara).
  • Os blocos Aguardar (logic.wait), Agendar template (message.schedule_template) e os gatilhos de inatividade (lead.attendance_inactive, lead.lead_inactive) viajam como os outros: tempo e unidade vão como estão, e o template vai por nome.

langchain

O config do agente no LangChain Agent: modelo, instruções, tools, skills e ajustes (retry, fallback, resumo, LangSmith e outros). Na escrita:
  • Cria uma versão nova, não publicada. Quem publica é uma pessoa, no painel.
  • Config igual ao atual não cria versão.
  • As chaves já gravadas (modelo, LangSmith, transcrição e modelos reserva, casados pelo nome) são mantidas quando o campo não vem ou vem vazio. Um texto de exemplo ("<removido>") grava por cima e o agente para de responder. O get_template devolve as chaves preenchidas: devolva o valor lido ou omita o campo.
  • Tool native (formato antigo) é convertida para http, o formato que o agente executa, mantendo o alvo.
  • Headers de tools vazios ou ausentes mantêm os atuais.
  • instructions.variables ausente mantém as variáveis atuais do prompt; {} apaga todas. Um {{x}} no prompt sem variável declarada gera nota. Para adaptar um agente a outro cliente, troque os valores das variáveis, não o prompt (Variáveis do prompt).
  • instructions.variables_meta diz, por variável, a pergunta (hint) e se o gestor a responde (gestor_editable). Ausente mantém o atual, independente de variables. Chave sem variável correspondente gera nota. O gestor só vê depois de a versão ser publicada.
  • A memória entre conversas liga com a tool { "type": "builtin", "name": "historico_conversas" } (Memória entre conversas).
  • Aprovação humana é sempre desligada, com nota.
  • Tools cujo alvo não existe no projeto não entram, com nota.
  • Gravar por cima de uma versão ainda não publicada gera nota.
  • Projeto no motor antigo: o bloco é ignorado, com nota.
  • A regra editável de uma ação da Zatten fica em _zatten.note, mas o modelo lê description. A escrita pelo MCP não recompõe description a partir da nota (só o painel faz isso, ao salvar a ação). Para mudar a regra pelo MCP, altere os dois: _zatten.note e o fim de description, com o mesmo texto. Veja Ações da Zatten.

Armadilhas

  • Lista inteira, sempre. Qualquer bloco de lista enviado com itens faltando deixa os que faltam como órfãos.
  • Renomear sem slug cria um item novo. Só columns, tags, attendant_teams, properties e skills renomeiam.
  • Nos blocos identificados por nome, mudar o name cria outro item e deixa o antigo como órfão.
  • Renomear coluna, tag ou departamento que o agente usa: mande também o bloco langchain (como veio do get_template) na mesma escrita. Só assim as tools do agente passam a apontar para o nome novo (o que cria uma versão não publicada). Sem isso, numa escrita futura do bloco langchain, a tool que aponta para o nome antigo é descartada, com nota.

Para saber mais