Update agent config
update_agent_configDestructiveIdempotent
Configura o agente conversacional de uma conta: persona (system_prompt), mensagem de boas-vindas, tom, modelo OpenAI, chave OpenAI e ativação. Sem target_user_id, configura o agente da PRÓPRIA conta autenticada. O administrador da plataforma pode passar target_user_id para configurar a conta de um cliente (ex: recém-criada com create_client_account). Cria a configuração se ainda não existir.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "update_agent_config"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tone | No | Tom do agente (opcional). | |
| model | No | Modelo OpenAI (opcional). | |
| is_active | No | Ativar ("true") ou desativar ("false") o agente. | |
| voice_name | No | Voz da resposta em áudio. coral (feminina, calorosa — padrão), nova (feminina, animada), shimmer (feminina, suave), sage (feminina, serena), ash (masculina, firme), ballad (masculina, suave), echo (masculina, neutra), verse (masculina, expressiva). Vazio = padrão. | |
| order_fields | No | CAMPOS PERSONALIZADOS da solicitação (mesma lista de Minha Conta › IA e atendimento › Campos personalizados): o que o agente coleta antes de registrar com create_service_order. Use para tudo que o agente precisa PERGUNTAR ao cliente (em vez de listar as perguntas no system_prompt, onde a regra é seguida só na maioria das vezes); preço NÃO vai aqui, vai no catálogo (create_product). JSON array [{"label":"Cidade e estado","required":true,"id":"cidade_estado"}] — "id" é opcional (gerado pelo rótulo). Os campos obrigatórios travam o registro até serem preenchidos; os opcionais vão para a solicitação se o cliente informar. Nome, telefone e e-mail são fixos e sempre ficam (pode mandar {"id":"email","required":false} para mudar só a obrigatoriedade deles). A lista enviada SUBSTITUI a atual inteira. Máx. 20 campos. "[]" volta só aos três padrão. | |
| system_prompt | No | Persona/instruções do agente, ex: "Você é a atendente da Confeitaria Doce Mel: simpática, tira dúvidas de produtos, informa preços e horários, e monta o pedido confirmando no fim." | |
| auto_tag_rules | No | JSON array de regras de fallback para marcação de tag: [{"matchText":"frase exata ou trecho do texto do agente","tag":"NomeDaTag"}]. Se a resposta gerada pelo agente contiver matchText (case-insensitive), a tag é aplicada via código mesmo que o modelo não tenha chamado a tool add_contact_tag — útil porque o LLM às vezes decide corretamente mas esquece de executar a tool call. Vazio ou omitido = sem fallback. | |
| business_hours | No | Horário de atendimento HUMANO. É AQUI que mora o horário da equipe (mesmo cartão "Horário de atendimento humano" de Minha Conta): o agente consulta em toda resposta. O horário mora só aqui, não no system_prompt nem na base, para não haver dois horários divergentes. Formato recomendado (estruturado): {"dias":{"1":{"inicio":"09:00","fim":"18:00","intervalo":{"inicio":"12:00","fim":"13:00"}},"6":{"inicio":"09:00","fim":"13:00"}},"observacao":"fechado em feriados"} — chave do dia: 0=domingo … 6=sábado. Texto livre ainda é aceito, mas é interpretado por regex que só entende UMA faixa e o mesmo horário a semana toda (sábado com horário próprio, por exemplo, sai errado). Diferente de calendar_instructions (janela de AGENDAMENTO): isso é usado quando o cliente pede pra falar com um humano — o agente sabe se está dentro ou fora do expediente (fuso America/Sao_Paulo) e avisa quando o time volta. Vazio ou omitido = recurso desativado. | |
| handoff_notify | No | PASSAGEM PARA A EQUIPE — quem recebe o aviso quando o agente passa a conversa: "equipe" (padrão: todos da conta com notificação ligada, como sempre foi), "dono_conversa" (só quem é dono da conversa; conversa sem dono avisa a equipe toda) ou "escolhidos" (exige handoff_notify_user_ids). | |
| openai_api_key | No | Chave da OpenAI da conta (opcional; deve começar com "sk-"). Criptografada ao salvar. Necessária para o agente responder e para indexar a KB. | |
| orders_enabled | No | Permitir o agente registrar pedidos (tool create_service_order). "true"/"false". | |
| target_user_id | No | ID da conta-alvo (opcional; APENAS o admin da plataforma pode usar). Padrão: a conta autenticada. | |
| customer_memory | No | Memória do cliente: o agente reconhece e lembra pedidos anteriores do contato. "true" liga (padrão), "false" desliga. | |
| kb_search_limit | No | Quantos trechos da base de conhecimento vão ao agente por mensagem (1 a 20; padrão 5). Aumente quando a conta tem MUITOS documentos e a informação existe na base mas não aparece na resposta — o teto é silencioso: o que fica fora do corte simplesmente não existe para aquela resposta. Caso real: com cardápio em texto E em foto, os textos ocupavam os 5 slots e a foto (que carrega o link da imagem) nunca chegava. | |
| timeout_message | No | Texto da mensagem de encerramento do Estágio 2. Padrão: "Olá! Como não recebemos sua resposta, encerramos o atendimento. Se precisar de ajuda, é só chamar novamente. 😊". | |
| welcome_message | No | Mensagem de boas-vindas / saudação inicial (opcional). | |
| async_qa_enabled | No | Revisão ASSÍNCRONA de qualidade (cron, não em tempo real): audita periodicamente respostas recentes do agente contra a base de conhecimento, usando um modelo de IA como juiz, pra detectar alucinação confiante (fato inventado ou errado dito sem hedge/evasiva) — complementa knowledge_gap_tracking_enabled, que só pega quando o agente ADMITE não saber. Achados viram registros em /insights com source "async_qa". "true"/"false" (padrão: false). | |
| handoff_channels | No | Por onde o aviso de passagem sai, separado por vírgula: "push" (notificação), "whatsapp" (números de Alertas de Mensagens), "email" (e-mail de quem é avisado). Padrão: "push,whatsapp". Ao menos um. | |
| reminder_message | No | Texto do lembrete do Estágio 1. Usado como fallback se ai_reminder_enabled="false" ou se a geração por IA falhar. Padrão: "Oi! Você ainda está aí? 😊". | |
| voice_reply_mode | No | Resposta em ÁUDIO no WhatsApp: "mirror" = quando o cliente manda áudio, o agente responde com mensagem de voz (OpenAI gpt-4o-mini-tts, gasta da chave OpenAI da conta, ~R$ 0,08 por minuto de fala); "off" = nunca (padrão). Link, e-mail, telefone e preço vão também por escrito depois do áudio; lista ou resposta longa vai só por texto. Só funciona em número conectado direto pela Meta. | |
| availability_intro | No | Frase antes da lista de horários. Use {quando} no começo: vira "Ainda hoje", "Amanhã" ou "Terça, 13/10". Ex.: "{quando} temos estes horários disponíveis:". Vazio = padrão. Quando o dia pedido está cheio, o sistema põe antes "Hoje já não tenho horário livre." sozinho. | |
| voice_instructions | No | Jeito de falar da voz, em linguagem natural (até 600 caracteres). Ex.: "fale como um consultor de construção, seguro e direto". Vazio = padrão (português do Brasil, simpático, ritmo calmo). | |
| ai_reminder_enabled | No | Gera o lembrete do Estágio 1 por IA, referenciando o que estava sendo discutido nas últimas mensagens (ex: "sobre o que vocês usam hoje pra organizar as demandas..."), em vez do texto fixo de reminder_message — tende a reengajar melhor quem abandonou NO MEIO de uma qualificação já engajada. "true"/"false" (padrão: false). | |
| handoff_max_replies | No | PASSAGEM PARA A EQUIPE — limite de respostas do agente por conversa (1 a 500). Ao bater, o agente para de responder naquela conversa, manda a mensagem de passagem (a mesma do "chamar um humano", que respeita o Horário de atendimento) e avisa a equipe com o resumo. Devolver a conversa ao agente ("Liberar") zera a contagem. Vazio = sem limite (padrão). | |
| prospect_reply_mode | No | Como o agente trata resposta de contato em cadência de prospecção. "off" = agente não responde, operador trata na mão (padrão). "draft" = agente gera a resposta mas NÃO envia, grava como nota interna pro operador revisar. "auto" = agente responde sozinho (com travas de opt-out/pausa do operador). | |
| availability_closing | No | Frase depois da lista de horários. Ex.: "Qual desses horários é melhor para você?". Vazio = "Qual desses horários prefere?". Sem nenhum dos três campos de horário, a lista sai no formato antigo, igual sempre. | |
| handoff_max_cost_usd | No | PASSAGEM PARA A EQUIPE — limite de gasto de IA por conversa, em dólares (ex.: "0.50"; até 100). Mesmo efeito do handoff_max_replies. Vazio = sem limite (padrão). | |
| order_notify_channel | No | Avisar o cliente ao mudar o estágio do pedido no Kanban. "off" (não avisa) | "auto" (WhatsApp; cai pra SMS fora da janela) | "whatsapp" | "sms". | |
| order_stage_messages | No | JSON das mensagens por estágio, ex: {"preparo":"","pronto":"Seu pedido está pronto!"}. Presença da chave = estágio avisa (vazio = texto padrão). Omitir o campo = usa os padrões (preparo/pronto/entregue). Variáveis: {nome}, {produto}. | |
| second_touch_enabled | No | SEGUNDO TOQUE — contato que NUNCA respondeu (diferente do Estágio 1/2, que exigem resposta prévia por compliance WABA: aqui é o oposto, só dispara quando o contato nunca respondeu nada e a janela de 24h nunca abriu). Envia um TEMPLATE aprovado (compliant fora da janela), não texto livre. Requer second_touch_template_name preenchido. Só se aplica a conversas de WhatsApp, e nunca a contato de cadência de prospecção (a cadência já cuida do follow-up). "true"/"false" (padrão: false). | |
| calendar_booking_mode | No | Ativa o fluxo de agendamento guiado (check_availability -> coleta de dados -> schedule_appointment) quando há uma conexão de agenda (Google Calendar ou NeetoCal) conectada na conta. "true"/"false". | |
| contact_tagging_enabled | No | Permitir o agente marcar tags no contato durante a conversa (tool add_contact_tag), disparando automações "tag:<nome>" (ex: marcar lead qualificado). "true" (padrão) ou "false". | |
| handoff_notify_user_ids | No | Ids de usuário da própria conta, separados por vírgula, para handoff_notify="escolhidos". | |
| availability_max_options | No | LISTA DE HORÁRIOS (check_availability): quantos horários mostrar, no máximo (1 a 26), sempre os mais cedo do dia. Vazio = todos do dia (padrão). Letras seguem A, B, C... e só as mostradas valem para a escolha. | |
| reminder_timeout_minutes | No | TIMEOUT DE INATIVIDADE — Estágio 1 (lembrete): minutos sem resposta do cliente pra disparar um lembrete "você ainda está aí?" automático. Só dispara se o cliente já respondeu pelo menos 1 vez na conversa (WABA compliance — nunca cutuca quem nunca abriu a janela) e nunca em contato de cadência de prospecção. Vazio/omitido = estágio desativado. | |
| typing_indicator_enabled | No | Mostra "digitando…" ao cliente no WhatsApp enquanto o agente prepara a resposta (só números Meta Direct). Marca a mensagem do cliente como lida nesse momento. "true"/"false" (padrão: ligado). | |
| operator_signature_enabled | No | Põe o primeiro nome de quem respondeu, em negrito, no topo de cada mensagem que a equipe envia pelo chat do WhatsApp (ex.: "*Vinicius:*" e o texto na linha de baixo), como o WhatsApp Business faz com vários atendentes. Vale para texto e legenda de mídia; não vale para template, SMS nem Instagram. O histórico do Radar guarda a mensagem sem o nome. "true"/"false" (padrão: desligado). | |
| second_touch_delay_minutes | No | Minutos sem resposta (desde a última mensagem do agente) pra disparar o segundo toque. Deve ser no mínimo 1440 (24h) — antes disso a janela ainda está aberta e o Estágio 1/2 (texto livre) é o caminho certo, não o template. Vazio/omitido = usa 1440 (24h). | |
| second_touch_template_lang | No | Idioma do template (padrão "pt_BR" se omitido). | |
| second_touch_template_name | No | Nome exato do template WABA APROVADO a enviar (ver list_whatsapp_templates), ex: "segundo_toque_sdr_ekyte_v2". O template PRECISA ter exatamente UMA variável {{1}} no corpo pro primeiro nome do contato (ex: "Oi {{1}}! ..."), nem mais nem menos — o cron sempre envia o primeiro nome como esse único parâmetro; a Meta rejeita se a contagem não bater ("Number of parameters does not match"). | |
| conversation_timeout_minutes | No | TIMEOUT DE INATIVIDADE — Estágio 2 (encerramento): minutos sem resposta pra enviar mensagem de encerramento e arquivar a conversa. Sempre relativo à ÚLTIMA mensagem do agente, independente do lembrete. Deve ficar com folga da janela de 24h do WABA (ex: até 22h) pra a mensagem de encerramento ainda conseguir ser enviada como texto livre. Vazio/omitido = estágio desativado. | |
| knowledge_gap_tracking_enabled | No | Registra internamente (tool flag_knowledge_gap + fallback heurístico) perguntas que o agente não soube responder, para revisão humana em /insights e evolução da KB/prompt. "true"/"false" (padrão: false). |