Toda ferramenta aceita também
intent e skill_version, dois campos opcionais
para a Zatten entender o uso (ver O que a Zatten registra).
O ciclo de uso
1
list_projects
Sempre que a pessoa citar um projeto pelo nome. As outras ferramentas exigem
o id e o nome exatos.
2
get_template
Guarde a
revision que vier.3
Plano e “sim”
Mostre o que vai mudar. Veja as regras.
4
update_template
Com a
revision da leitura e só os blocos que mudam.5
Leia as notes e releia o projeto
A resposta não traz a revision nova. Para registrar o estado novo (snapshot)
ou editar de novo, chame
get_template outra vez.O par project_id + project_name
get_template e update_template pedem o id do projeto e o nome exato, como
vieram de list_projects. O servidor confere os dois contra o banco. Se não
casarem, recusa e diz de quem é o id enviado.
É a trava mais barata contra mexer no cliente errado: quem confunde dois projetos
erra o id ou o nome, e errar os dois do mesmo jeito é muito menos provável.
whoami
Confirma a conta conectada. Use antes de alterar qualquer coisa, para dizer à pessoa em nome de quem você está agindo.list_projects
Os projetos que a conexão alcança, em ordem de nome. A lista é o limite da conexão: projeto que não aparece aqui não pode ser lido nem alterado, nem pelo id. Cada projeto traz, além do id e do nome, o que ajuda a se orientar: a organização (a pasta do painel), o plano, se está pago e se o WhatsApp está conectado. O detalhe (limites, uso, versões do agente) vem noget_template.
get_template
O projeto inteiro em JSON: funil, tags, propriedades, skills, automações, fluxos, templates da Meta e o agente. A referência de cada bloco está em Referência do template.- O config do agente vem da versão mais nova, publicada ou não. Assim quem edita não apaga um rascunho que alguém deixou no painel.
- Todos os templates da Meta do projeto vêm no bloco
meta_templates. - A
revisioné a marca do estado atual. Duas leituras sem mudança no meio devolvem a mesma; se mudou, alguém mexeu. - Ao lado do template vem
project: as informações do projeto que não são configuração (organização, plano e uso, cobrança, WhatsApp e as versões do agente). Ver abaixo. - O JSON traz endereços de webhook e de MCP, headers e as chaves do agente (do
modelo e do LangSmith), preenchidos. Trate-o como confidencial: nunca mostre uma
chave na conversa nem a grave em arquivo. O snapshot é gravado com as chaves
trocadas por
"<removido>"(ver Organizar sua agência).
update_template
Aplica alterações. Cria o que falta, atualiza o que existe e nunca apaga. Envie só os blocos que vai mudar: o que não vier não é tocado. Mas o bloco enviado é declarado por inteiro, e o que existir no projeto e faltar no bloco volta como órfão. As regras completas (o que conta como “vazio”, ligar e desligar, renomear, referências por nome, o agente) estão em Como uma escrita funciona. O queupdate_template não faz:
- apagar qualquer coisa;
- publicar a versão do agente (cria uma versão nova, não publicada);
- enviar template à Meta (o envio é pelo painel);
- migrar o projeto de motor;
- reescrever o desenho de um fluxo que já existe;
- gravar
llm_attendant.functions; - ligar a aprovação humana do agente.
update_template como ação destrutiva e costumam pedir
confirmação. Não é que apague: é que altera a configuração de um cliente real.
create_project
Cria um projeto novo na conta. Três jeitos:- Em branco: só o nome. Nasce como o “em branco” do painel: funil Novo Contato / Atendimento Humano / Ganho / Perdido e o departamento Atendimento.
- Com blocos: nome +
template, no mesmo formato doupdate_template. Cada bloco enviado substitui o do em branco por inteiro (mandarcolumnscom três colunas dá um funil de três). - Duplicando: nome +
source_project_id. O projeto novo nasce como cópia do outro, inclusive chaves e endereços, que são lidos no servidor e não passam pela conversa. As variáveis do prompt nascem vazias, salvo comkeep_variable_values: true: o projeto novo é de outro cliente. As perguntas do gestor vão junto, e o agente só liga depois que as variáveis usadas no prompt forem preenchidas. Pergunte à pessoa qual dos dois ela quer.
test_agent
Manda uma mensagem ao agente de IA do projeto, como se fosse o contato de teste no WhatsApp, e devolve o que ele respondeu, as tools que chamou (com argumentos e resultado) e o que falhou. É o chat de teste do painel, pelo MCP. É o que fecha o ciclo de construção do agente: oupdate_template cria uma versão
nova → o test_agent roda essa versão → o assistente lê a resposta e as tools →
ajusta → testa de novo. Veja Construir o agente iterando.
- Roda a versão mais nova, publicada ou não. O WhatsApp continua na publicada até uma pessoa publicar no painel. O assistente nunca publica.
- As tools executam de verdade. Uma tool HTTP chama o sistema do cliente (um agendamento de teste vira agendamento real); as ações da Zatten mexem no contato de teste. Antes da primeira rodada, o assistente avisa a pessoa e espera o “sim”; com ele, itera sem pedir de novo a cada rodada.
- Conversa: a resposta traz
thread_id. Mandado de volta, continua a mesma conversa de teste. Só conversas de teste do projeto são aceitas: uma conversa real de lead nunca é lida nem continuada por aqui. - Só no LangChain Agent, e exige conexão de Leitura e edição. Cada rodada leva até 3 minutos.
test_agent também não testa.
create_organization, rename_organization e move_project
As organizações são as pastas do painel que agrupam projetos. Para a agência, costumam ser o estágio do cliente: “Prospects”, “Implantação”, “Produção”. Toda conta nasce com uma chamada “Principal”. Veja Organizações e projetos.create_organizationcria; nome repetido é recusado.rename_organizationrenomeia; os projetos dela não mudam.move_projectmove um projeto para outra organização. Funil, agente, automações e leads vão juntos, e o acesso dos membros vai junto: quem via o projeto continua vendo.- Apagar organização não existe pelo MCP. É no painel, com o assistente guiando.
find_contacts
Procura contatos (leads) de um projeto. É busca, não exportação: serve para chegar ao número de um contato e, com ele, ler a conversa pela API do dia a dia.- Exige pelo menos um filtro:
query(parte do nome ou do número),column,tag, ou um período da última interação. - Devolve no máximo 20, os de interação mais recente.
- Só identificação: nome, número, coluna, tags e datas. Nunca o conteúdo das mensagens, notas ou propriedades.
- Até 30 buscas por minuto por conexão.
get_metrics
Os números de um projeto num mês, os mesmos da tela de Métricas (Métricas), pela mesma conta: contatos novos (anúncio x orgânico), mensagens recebidas e enviadas, mensagens da IA x de humanos, tokens, o funil por coluna, os anúncios que trouxeram contatos e as conversões. Total e por dia. Para avaliar como um agente está indo, montar o relatório mensal do cliente final ou mostrar resultado numa renovação (Operar a agência).list_members
Os membros da conta: nome, e-mail, papel, os projetos que cada um vê e os departamentos em que está, com se recebe os leads de cada um. Para diagnosticar acesso (“por que a Ana não vê o projeto da clínica?”, “quem recebe os leads do Comercial?”) e para ler antes de mudar.create_member e update_member_access
Criam membros e mudam o acesso deles, com as mesmas regras de Configurações → Gerenciar Acessos (Usuários e permissões).create_membercria o login com nome, e-mail, senha e papel (Gestor, Editor ou Visualizador). O membro nasce sem projetos.update_member_accessmuda, pelo e-mail, o papel, o nome, a senha, os projetos e os departamentos de um membro. Só muda o que vier: projeto ou departamento que não está no pedido fica como está.- “Recebe leads” é por departamento, não do membro: a mesma pessoa pode receber no Comercial e não no Suporte.
- Entrar num departamento libera o projeto. Tirar o projeto
(
access: false) tira o membro dos departamentos dele. - A senha é a que a pessoa escolher: o assistente pergunta. O white label não tem “esqueci a senha”, então trocar a senha também é por aqui (ou no painel). A senha nunca volta na resposta e não entra no registro de uso.
- o departamento não existe no projeto (a recusa lista os que existem);
- o membro tem leads atribuídos num departamento de onde sairia;
- o departamento ficaria sem ninguém recebendo leads;
- o projeto chegou ao limite de usuários do plano.
update_template
(bloco attendant_teams).
Quem pode: conexão de Leitura e edição, com acesso a todos os
projetos, gerada por um Admin da conta.
get_white_label
A configuração de white label da conta (não de um projeto): nome da marca, subdomínio e endereço do painel, domínio próprio, logo, favicon, cores e contato. Veja White label. Só leitura. Mudar marca ou domínio é com a pessoa, em Configurações → Minha Empresa e Configurações → Domínios Customizados. Se o domínio próprio está verificado, é a segunda tela que diz.send_feedback
Conta à Zatten como terminou a tarefa que a pessoa pediu: feita, feita em parte ou travada, e onde travou. Não muda nada no projeto e não aparece para a pessoa: é o que a Zatten usa para melhorar a skill, esta doc e as ferramentas. O assistente chama uma vez no fim de cada tarefa que usou o MCP.O que a Zatten registra
Cada chamada ao MCP deixa um registro de uso do lado da Zatten, para melhorar a skill, a doc e as ferramentas:- a ferramenta, o projeto, se deu certo e quanto tempo levou;
- o assistente que chamou (Claude Code, Codex…), pelo nome que ele informa;
- um resumo sem dado do cliente: quais blocos foram enviados, quantas mudanças e órfãos, quais tools o agente chamou num teste;
- o
intente osend_feedback, quando o assistente os manda.
Erros
Quando a operação é recusada, nada é alterado. As mensagens dizem o que fazer:Armadilhas
ok: truenão quer dizer que tudo foi feito. Recusas parciais (automação que não ligou por falta de endereço, conversão cuja coluna não existe, template da Meta não enviado) aparecem só nasnotes.- A revision não vem na resposta da escrita. Duas escritas seguidas com a mesma revision: a segunda é recusada, porque a primeira já mudou o projeto.
- Texto de exemplo numa chave do
langchain.configgrava por cima. Chave ausente,nullou""mantém a atual;"<removido>"ou"sk-..."substitui e derruba o agente. Devolva o valor lido ou omita o campo. projectnão é configuração. Não devolva o blocoprojectdoget_templatenoupdate_template: ele é só leitura e fica fora do template.- Testar executa. O
test_agentroda as tools do agente de verdade. Uma tool que mexe em sistema externo age nele. - Renomear o projeto muda o par. Se o bloco
metatrocar o nome do projeto, a próxima chamada precisa do nome novo. - A senha do membro é segredo. Pergunte qual é, nunca invente e nunca a
repita (plano, chat, arquivo, memória,
intent). Ela não volta na resposta. - Membro novo não vê nada. O
create_membercria sem projetos; o acesso vem noupdate_member_access. - A nota sobre templates da Meta cita uma opção que o MCP não tem. Quando faltam
templates, a nota sugere
submit_meta_templates: true. Pelo MCP essa opção não existe: o envio à Meta é feito por uma pessoa, no painel (WhatsApp → Templates).
Para saber mais
- Como uma escrita funciona
- Referência do template
- Instalar a skill e o MCP
- API de template (REST): o mesmo motor, por HTTP, com a chave do projeto.
- MCP: especificação, ferramentas. Termos para buscar: “MCP tools”, “tool annotations destructiveHint”.