Referência de automações do WhatsApp: gatilhos, passos, variáveis e limites
As automações do easyCoexistence em um número do WhatsApp começam por uma mensagem que chega, um contato que recebe uma tag ou uma chamada do seu sistema. Uma mensagem tem quatro correspondências: Todas as mensagens, Tem palavra-chave, Primeira mensagem e Fora do horário. Depois vêm os passos, até 30 em uma linha e 60 no total, com ramificações, perguntas e agentes de IA. Cada mensagem aciona no máximo uma automação, e as regras de palavra-chave têm prioridade.
Passos em uma linha, 60 no total, ramificações aninhadas em até 4 níveis; Parar e Voltar a um passo só podem encerrar uma linha.
Por automação, com até 100 caracteres cada; basta uma delas, e maiúsculas e minúsculas não fazem diferença.
Caracteres permitidos nas Instruções de um passo Responder com IA, cujas respostas têm um limite entre 50 e 2.000 tokens.
Duração máxima de um único passo Esperar, 23 horas, para que o próximo passo de texto ainda caia dentro da janela de atendimento de 24 horas da Meta.
Tempo que o seu webhook tem para responder antes de Chamar meu webhook falhar; um campo reply na resposta é enviado ao cliente.
Retenção das execuções, com cada mensagem inicial e a resposta; o texto das mensagens é apagado após a retenção que você escolher (30, 90 ou 365 dias, 90 por padrão).
Quais gatilhos e correspondências uma automação de WhatsApp pode usar?
O gatilho principal, "Chega uma mensagem" (message_received), dispara quando um cliente escreve para o número: texto, fotos, vídeo, documentos, áudio, figurinhas, localizações, cartões de contato, respostas de botão e de lista, e pedidos. Uma nota de voz é transcrita com a sua chave da OpenAI ou do OpenRouter e guardada como "[voice message]" seguido das palavras, que uma palavra-chave pode encontrar; sem essa chave, ela fica só "[voice message]". Reações, status e avisos do sistema nunca iniciam uma execução, e conversas de grupo não chegam à API em um número de Coexistência. Dois outros gatilhos não começam por uma mensagem. "Um contato recebe uma tag" (tag_added) dispara cada vez que um contato acessível pelo número recebe a tag que você indicar, por um fluxo, por um agente de IA, por você em Conversas ou por update_contact. "Seu sistema chama uma URL" (webhook_received) dispara quando o seu próprio sistema faz um POST em JSON com um número de telefone para a URL da automação, com o segredo da automação como Bearer token, para um novo pedido ou uma reserva; o corpo, de até 20 KB, fica disponível como {{vars.webhook.*}}. Nos dois, {{message}} fica vazio e uma pessoa que não escreveu nas últimas 24 horas só pode receber um send_template. Não existe gatilho de agendamento. No gatilho de mensagem, Fora do horário considera os dias marcados em "Aberto em" como abertos entre De e Até, em um fuso horário IANA, como America/Sao_Paulo; um Até anterior ao De indica um turno que vira a noite (22:00 a 06:00), e um dia não marcado conta como fechado o dia inteiro. Na API, hours recebe timezone, days (1 = segunda a 7 = domingo, os dias em que você está aberto), start e end. Primeira mensagem dispara quando o easyCoexistence cria um registro para a conversa: a primeira mensagem de um cliente desde que uma automação foi ligada no número, inclusive de clientes antigos, ou a primeira depois de 30 dias sem conversa. Uma conversa que você abriu pelo celular já conta como vista.
Como funcionam os modos de palavra-chave?
Em "Onde a palavra deve estar", Contém ("Em qualquer parte da mensagem") é o padrão, Começa com é "No início" e É exatamente é "A mensagem inteira"; na API, keywordMode é contains, starts_with ou exact. A comparação descarta os espaços no início e no fim da mensagem e ignora maiúsculas e minúsculas, mas não ignora acentos nem pontuação, e Contém também encontra a palavra-chave dentro de palavras maiores. A caixa "Testar", abaixo de Palavras-chave, responde "Executa: há correspondência" com a palavra-chave, ou "Não executa: nenhuma palavra-chave corresponde", para qualquer exemplo que você digitar.
| Matches | Does not match | |
|---|---|---|
| Contains "price" | What is the price? · PRICES please | How much is it? |
| Contains "oi" | Oi! · Boa noite (inside noite) | Olá |
| Starts with "menu" | Menu please | Can I see the menu? |
| Is exactly "menu" | Menu · menu with spaces around it | menu? · the menu |
| Contains "preço" | Qual o preço? | Qual o preco? |
O que cada passo faz e quais campos ele recebe?
Os passos rodam de cima para baixo, até 30 em uma linha e 60 em uma automação, ramificações incluídas, e pelo menos um deles precisa fazer algo além de Esperar, Parar, Dividir em caminhos, IA escolhe o caminho e Voltar a um passo. Um passo com ramificação tem uma linha de passos para cada caminho, mais uma linha Caso contrário, e as ramificações se aninham até 4 níveis. No menu "Escolher um passo", cada um mostra um nome e uma descrição curta, ambos citados abaixo para os seis passos básicos. Fazer uma pergunta (ask) envia a sua Mensagem com até 10 botões, dos quais 3 aparecem como botões tocáveis e os demais são listados e respondidos por número, espera até 1.380 minutos pela resposta e a salva em um campo do contato como texto, e-mail, número, telefone ou um dos botões; uma resposta errada faz a pergunta voltar até 3 vezes. Respostas do agente (agent) entrega a mensagem a um dos seus agentes de IA, Enviar imagem ou arquivo (send_file) envia uma imagem ou um PDF dos seus arquivos, e Passar para uma pessoa (handoff) pausa o bot naquela conversa por 1 a 168 horas, 24 por padrão, e avisa você por e-mail. Dividir em caminhos (condition) e IA escolhe o caminho (ai_decide) ramificam por regras ou pelo sentido da mensagem. IA salva detalhes (ai_extract), Salvar no contato (set_field) e Tag (tag) gravam campos e tags do contato, e Chamar uma API (http_request) chama qualquer API HTTPS e guarda a resposta em JSON como {{vars.<nome>...}}. Iniciar automação (start_automation) executa outra automação para a mesma pessoa, no máximo 3 níveis, Voltar a um passo (goto) salta para o id de um passo para fazer um laço, e Avisar-me (notify_owner) envia um e-mail para você, no máximo 20 por hora por automação. Se um passo falhar, os passos seguintes são pulados e a execução termina como Falhou. Chamar meu webhook faz um POST em JSON com event "automation.step", dry_run, run_id, o número, o contato (wa_id, name), a mensagem (id, type, text, at) e até 10 mensagens recentes da conversa, assinado em X-EC-Signature como t=<unix>,v1=<HMAC-SHA256 de "<t>.<body>"> com o "Segredo de assinatura" do passo. A URL precisa ser pública e em HTTPS, e redirecionamentos não são seguidos.
Quais variáveis os passos podem preencher?
Quatro são preenchidas a partir da mensagem que iniciou a execução, escritas entre chaves duplas; {{contact.<field>}} adiciona um campo do contato (também contact.name e contact.phone) e {{vars.<path>}} o que passos anteriores salvaram, como a resposta de um passo Chamar uma API. Elas funcionam na Mensagem de Responder com texto, nas variáveis do corpo de um template, nas Instruções de Responder com IA e no texto de outros passos, como Fazer uma pergunta; nas variáveis de um template, os chips "Inserir:" as adicionam. Um valor desconhecido, como um perfil sem nome, fica vazio. Envios de template levam apenas variáveis do corpo, por posição, então um template com variáveis nomeadas, com imagem ou variável no cabeçalho, ou com um botão que tenha variável ainda não pode ser escolhido, e uma variável vazia faz a Meta recusar o envio.
- {{
first_name}}: a primeira palavra do nome de perfil do cliente no WhatsApp ("Primeiro nome"). - {{name}}: o nome de perfil completo ("Nome completo").
- {{message}}: o texto da mensagem ou, se não houver texto, um marcador como "[image]" seguido da legenda ("Mensagem do cliente").
- {{phone}}: o número do cliente em formato internacional, só dígitos e sem o sinal de mais, como 5511999998888 ("Telefone do cliente").
- Em um teste, o cliente é "Cliente de teste" e o telefone é 15550000000.
Quais são as configurações e seus padrões?
Duas configurações ficam em "Avançado", o botão ao lado da chave Ligado no editor, e o passo de IA tem mais duas próprias. Um campo omitido assume o valor padrão, tanto no editor quanto pelo create_automation. Os tempos limite são fixos, não configuráveis: uma resposta de IA tem 45 segundos e um webhook, 20 segundos. O nome de uma automação aceita até 120 caracteres. Um agente de IA tem configurações próprias: mensagens anteriores que ele lê, de 0 a 40 (padrão 20), resposta mais longa de 100 a 4.000 tokens (padrão 800), até 10 chamadas de ferramenta por resposta (padrão 5) e horas de transferência para uma pessoa, de 1 a 168 (padrão 24).
Qual automação responde quando várias se aplicam?
No máximo uma, escolhida em uma ordem fixa: Tem palavra-chave primeiro, depois Primeira mensagem, depois Fora do horário e por último Todas as mensagens; dentro do mesmo tipo, vale a automação mais antiga. Só concorrem automações Ligadas e não pausadas, então, quando a regra de palavra-chave está Desligada ou pausada por uma chave de IA recusada, quem responde é a regra geral. Duas consequências costumam surpreender. Um cliente novo que escreve à noite recebe a automação Primeira mensagem, não a Fora do horário, porque Primeira mensagem tem prioridade maior. E uma mensagem respondida por uma automação de palavra-chave nunca chega a um agente de IA nem a um passo Responder com IA em Todas as mensagens; se quiser os dois, coloque o agente ou o passo de IA dentro da automação de palavra-chave. Uma mensagem que responde a um passo Fazer uma pergunta aberto pertence a essa pergunta, e nenhuma outra automação começa com ela. Automações de tag e de webhook começam pelos próprios eventos e não participam dessa ordem.
Quais proteções vêm embutidas?
O executor aplica estas proteções sem nenhuma configuração, e, quando uma delas interrompe uma execução, o motivo exibido na aba Execuções indica qual foi:
- Uma mensagem que a Meta entrega duas vezes inicia uma só execução: duplicatas são descartadas pelo id da mensagem.
- Reações, status, os envios da própria automação e os ecos das mensagens que você envia pelo app nunca iniciam uma execução.
- Responder com texto, Fazer uma pergunta, Enviar imagem ou arquivo, Responder com IA, a resposta de um agente e a resposta de um webhook exigem que a última mensagem do cliente tenha menos de 24 horas; Enviar template não.
- Uma resposta que você digita no app do WhatsApp Business pausa a automação naquela conversa, e uma execução aguardando ali pula os passos restantes.
- Uma mensagem mais nova que inicia a mesma automação em uma conversa substitui a execução que ainda aguarda em um passo Esperar naquela conversa; uma mensagem que responde a uma pergunta aberta vai para essa pergunta.
- Os envios de um número têm um intervalo mínimo de 100 ms entre si, abaixo do limite de 20 por segundo da Meta para números de Coexistência.
- Quando um passo falha, você recebe um e-mail, no máximo uma vez por automação a cada 6 horas; uma chave de IA recusada pausa as automações que usam aquele provedor e gera um único e-mail.
O que a ferramenta create_automation recebe?
O conector MCP tem dezenove ferramentas para automações e o que elas usam. Oito são de automações: set_inbound_mode, list_automations, create_automation, update_automation, delete_automation, test_automation, list_automation_runs e get_automation_run. Oito são de agentes e arquivos: list_agents, list_files, create_agent, update_agent, delete_agent, add_agent_knowledge, delete_agent_knowledge e test_agent. Três são de pessoas: list_conversations, get_conversation e update_contact. create_automation recebe connection_id (de list_numbers), name, enabled, trigger, steps e settings, em snake_case, como keyword_mode e max_tokens; camelCase também é aceito. Os objetos de passo são reply_text {text}, send_template {name, language, params}, ai_reply {provider, model, prompt, history, max_tokens}, call_webhook {url} e wait {minutes}, depois ask {text, buttons, save_to, expect, retry_text, wait_minutes}, agent {agent_id, wait_seconds}, send_file {file_id, caption}, condition {paths, otherwise}, ai_decide {provider, model, instructions, paths, otherwise}, ai_extract {provider, model, fields}, set_field {key, value}, tag {action, tag}, http_request {method, url, headers, body, save_as}, start_automation {automation_id}, handoff {hours, note}, notify_owner {text}, goto {to} e stop. update_automation mantém os campos que você omitir, e steps, quando informado, substitui a lista inteira. Os erros indicam o campo, como "trigger.keywords: Add at least one keyword", "steps.2: Stop must be the last step of its line" ou "steps.0: save your openai API key on the Automations page first". Chaves de IA nunca passam pelo MCP. No exemplo, o passo Esperar de 1 minuto faz com que um cliente que manda várias linhas seguidas receba uma só resposta.
{
"connection_id": "<connection_id from list_numbers>",
"name": "After-hours assistant",
"enabled": false,
"trigger": {
"type": "message_received",
"match": "outside_hours",
"hours": {
"timezone": "America/Sao_Paulo",
"days": [1, 2, 3, 4, 5, 6],
"start": "08:00",
"end": "18:00"
}
},
"steps": [
{ "type": "wait", "minutes": 1 },
{
"type": "ai_reply",
"provider": "openrouter",
"model": "google/gemini-omni-1.2-flash",
"prompt": "You are the assistant of Ana's Bakery. We are closed and open at 8:00. Answer questions about products; a person confirms orders in the morning.",
"history": 10,
"max_tokens": 600
}
],
"settings": { "takeover_hours": 4, "ai_max_per_hour": 10 }
}Erros comuns
- Usar uma palavra-chave de duas letras com Contém. "oi" também corresponde a "noite" e "boi", então a automação responde a mensagens para as quais não foi feita; use É exatamente ou uma palavra-chave mais longa.
- Cadastrar só a grafia com acento. A comparação ignora maiúsculas, mas não acentos, então "preço" não pega quem digita "preco"; adicione as duas.
- Achar que Primeira mensagem ignora clientes frequentes. Ela dispara para qualquer cliente cuja conversa o easyCoexistence não viu nos últimos 30 dias, então clientes antigos recebem as boas-vindas na primeira mensagem depois que você a liga.
- Escolher um template que exige imagem no cabeçalho ou botão de copiar código. As automações preenchem apenas variáveis do corpo, então o editor mostra o template mas não deixa escolhê-lo; configurado pelo MCP, o envio é recusado pela Meta e a execução falha.
O easyCoexistence executa estas automações no número do WhatsApp Business que você continua usando no app, pela Cloud API da Meta e pela Coexistência. Crie-as no editor, em Automações, Nova automação, ou deixe o ChatGPT ou o Claude chamarem create_automation e test_automation pelo conector MCP, que tem mais de 30 ferramentas. De R$ 29,90 a R$ 3,90 por número por mês, caindo conforme você adiciona números, com os 3 primeiros dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
Uma automação pode seguir caminhos diferentes conforme o que o cliente diz?
Sim. Dividir em caminhos (condition) ramifica pelo texto da mensagem, por um campo do contato, por uma tag, por uma resposta anterior de API ou pelo seu horário de funcionamento, e IA escolhe o caminho (ai_decide) decide pelo sentido, em qualquer idioma, no seu próprio modelo. Cada caminho tem a sua própria linha de passos, e uma linha Caso contrário recebe o restante. Você também pode deixar a decisão com o n8n ou com o seu backend usando Chamar meu webhook, que pode devolver um {"reply": "..."} diferente para cada caso.
Existe limite de automações ou de execuções?
Não há limite de execuções nem cobrança extra por elas, e também não há limite de quantas automações um número pode ter. Os limites que valem são por conversa: respostas de IA por hora, a regra de 24 horas da Meta para texto e a pausa depois que você responde pelo celular.
Posso mover ou copiar uma automação para outro número?
Para mover, altere a Conexão no editor ou use update_automation com um novo connection_id; execuções ainda aguardando no número antigo terminam como substituídas. Para copiar, peça à sua IA que leia a automação com list_automations e crie o mesmo gatilho e os mesmos passos no outro número.
O que acontece com as execuções em espera quando eu edito uma automação?
Elas continuam. Uma execução parada em um passo Esperar retoma no número de passo seguinte da automação, na versão salva no momento em que é retomada, então uma edição pode mudar o que ela envia. Para interrompê-las, desligue a automação: elas terminam como Pulada, com "Automation is off".
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em