Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Referência de automações WhatsApp: gatilhos, passos, variáveis e limites

As automações da easyCoexistence num número WhatsApp arrancam com uma mensagem que chega, um contacto que recebe uma etiqueta ou uma chamada do seu sistema. Uma mensagem tem quatro correspondências: Todas as mensagens, Tem palavra-chave, Primeira mensagem e Fora de horas. Depois seguem-se passos, até 30 numa linha e 60 no total, com ramificações, perguntas e agentes de IA. Uma mensagem recebe no máximo uma automação, e as regras de palavra-chave são avaliadas primeiro.

30 steps

Passos numa linha, 60 no total, ramificações aninhadas até 4 níveis; Parar e Voltar a um passo só podem terminar uma linha.

30 keywords

Por automação, até 100 caracteres em cada palavra-chave; basta uma, e as maiúsculas não contam.

20,000

Caracteres permitidos nas Instruções de um passo Responder com IA, cujas respostas ficam limitadas a 50 a 2,000 tokens.

1,380 min

Passo Esperar mais longo, de cada vez: 23 horas, para que o passo de texto seguinte continue dentro da janela de 24 horas da Meta.

20 seconds

Tempo que o webhook tem para responder antes de Chamar o meu webhook falhar; um campo reply na resposta é enviado ao cliente.

30 days

Retenção das execuções, com cada mensagem inicial e resposta; o texto das mensagens é eliminado ao fim da retenção que escolher (30, 90 ou 365 dias, 90 por predefinição).

Que gatilhos e correspondências pode usar uma automação WhatsApp?

O gatilho principal, «Chega uma mensagem» (message_received), dispara quando um cliente escreve para o número: texto, fotos, vídeos, documentos, áudios, autocolantes, localizações, cartões de contacto, respostas de botões e listas, e encomendas. Uma nota de voz é transcrita com a sua chave da OpenAI ou do OpenRouter e guardada como «[voice message]» seguida das palavras, que uma palavra-chave pode encontrar; sem essa chave fica «[voice message]». Reações, estados e avisos do sistema nunca iniciam uma execução, e as conversas de grupo não chegam à API num número Coexistence. Mais dois gatilhos não começam por uma mensagem. «Um contacto recebe uma etiqueta» (tag_added) dispara de cada vez que um contacto acessível no número recebe a etiqueta que indicar, a partir de um fluxo, de um agente de IA, de si em Conversas ou de update_contact. «O seu sistema chama um URL» (webhook_received) dispara quando o seu próprio sistema envia um POST em JSON com um número de telefone para o URL da automação, com o segredo da automação como Bearer token, por exemplo para uma nova encomenda ou uma reserva; o corpo, até 20 KB, fica disponível como {{vars.webhook.*}}. Em ambos, {{message}} está 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 de horas considera abertos os dias marcados em «Aberto em» entre De e Até, num fuso horário IANA como America/Sao_Paulo; um Até anterior a De é um turno noturno (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-feira a 7 = domingo, os dias em que está aberto), e start e end. Primeira mensagem dispara quando a easyCoexistence cria um registo para a conversa: a primeira mensagem de um cliente desde que uma automação foi ativada no número, incluindo clientes antigos, ou a primeira depois de 30 dias de silêncio. Uma conversa que abriu a partir do telemóvel já conta como vista.

Every message (any)Runs on whatever the customer writes, when no more specific automation matched.
Has keyword (keyword)Runs when the message holds one of up to 30 keywords, in one of three modes.
First message (first_message)Runs on a chat easyCoexistence has not seen, or after 30 days without a message from that customer.
After hours (outside_hours)Runs while you are closed: Timezone, Open on days, and From and To in 24-hour HH:MM.

Como funcionam os modos de palavra-chave?

Em «Onde a palavra tem de estar», Contém («Em qualquer parte da mensagem») é a predefinição, Começa por é «No início» e É exatamente é «A mensagem inteira»; na API, keywordMode é contains, starts_with ou exact. A correspondência retira os espaços em volta da mensagem e ignora maiúsculas e minúsculas, mas não ignora acentos nem pontuação, e Contém também corresponde dentro de palavras mais longas. A caixa «Testar», sob Palavras-chave, responde «Executa: corresponde» com a palavra-chave, ou «Não executa: nenhuma palavra-chave corresponde», para qualquer exemplo que escreva.

MatchesDoes not match
Contains "price"What is the price? · PRICES pleaseHow much is it?
Contains "oi"Oi! · Boa noite (inside noite)Olá
Starts with "menu"Menu pleaseCan I see the menu?
Is exactly "menu"Menu · menu with spaces around itmenu? · the menu
Contains "preço"Qual o preço?Qual o preco?

O que faz cada passo e que campos recebe?

Os passos correm de cima para baixo, até 30 por linha e 60 por automação, ramificações incluídas, e pelo menos um tem de fazer algo além de Esperar, Parar, Dividir em caminhos, A IA escolhe o caminho e Voltar a um passo. Um passo de ramificação contém uma linha de passos por caminho mais uma linha Caso contrário, e as ramificações encaixam-se até 4 níveis. No menu «Escolher um passo», cada um mostra um nome e uma linha 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 para tocar e os restantes são listados e respondidos por número, espera até 1380 minutos pela resposta e guarda-a num campo do contacto como texto, email, número, telefone ou um dos botões; uma resposta errada leva a repetir a pergunta até 3 vezes. Resposta do agente (agent) entrega a mensagem a um dos seus agentes de IA, Enviar uma imagem ou ficheiro (send_file) envia uma imagem ou um PDF dos seus ficheiros, e Passar a uma pessoa (handoff) pausa o bot nessa conversa durante 1 a 168 horas, 24 por predefinição, e envia-lhe um email. Dividir em caminhos (condition) e A IA escolhe o caminho (ai_decide) ramificam por regras ou pelo significado. A IA guarda dados (ai_extract), Guardar no contacto (set_field) e Etiquetar (tag) escrevem campos e etiquetas do contacto, e Chamar uma API (http_request) chama qualquer API HTTPS e guarda a sua resposta JSON como {{vars.<name>...}}. 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 repetir, e Avisar-me (notify_owner) envia-lhe um email, no máximo 20 por hora por automação. Se um passo falhar, os passos seguintes são ignorados e a execução termina como Falhada. Chamar o meu webhook envia um POST em JSON com event «automation.step», dry_run, run_id, o número, o contacto (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. O URL do passo tem de ser HTTPS público, e os redirecionamentos não são seguidos.

Reply with text (reply_text)"Send a fixed message": a Message of up to 4,096 characters, with variables.
Send a template (send_template)"Send an approved template": Template name, Language code, up to 20 body variables by position.
Reply with AI (ai_reply)"Your AI writes the reply": Provider, Model, Instructions, Earlier messages it reads, Longest reply (tokens).
Call my webhook (call_webhook)"Hand off to n8n or your backend": a Webhook URL; {"reply": "..."} returned within 20 seconds is sent.
Wait (wait)"Pause before the next step": 1 to 1,380 Minutes; your reply from the phone skips the rest.
Stop (stop)"End the automation": allowed only as the last step of its line.

Que variáveis podem os passos preencher?

Quatro são preenchidas a partir da mensagem que iniciou a execução, escritas entre chavetas duplas; {{contact.<field>}} acrescenta um campo do contacto (também contact.name e contact.phone) e {{vars.<path>}} o que os passos anteriores guardaram, como a resposta de um passo Chamar uma API. 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 atalhos «Inserir:» acrescentam-nas. Um valor desconhecido, como um perfil sem nome, fica vazio. Os envios de template levam apenas variáveis do corpo, por posição, por isso um template com variáveis com nome, uma imagem de cabeçalho ou uma variável no cabeçalho, ou um botão com 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 no WhatsApp do cliente («Primeiro nome»).
  • {{name}}: o nome de perfil completo («Nome completo»).
  • {{message}}: o texto da mensagem, ou o seu marcador, como «[image]», mais a legenda («A mensagem do cliente»).
  • {{phone}}: o número do cliente em dígitos internacionais, sem o sinal de mais, como 5511999998888 («Telefone do cliente»).
  • Num teste, o cliente é «Cliente de teste» e o telefone é 15550000000.

Quais são as definições e as respetivas predefinições?

Duas definições estão em «Avançado», o botão ao lado do interruptor de ativação no editor, e o passo de IA traz mais duas próprias. Um campo omitido assume a sua predefinição, tanto no editor como através de create_automation. Os tempos limite são fixos e não se definem: uma resposta de IA tem 45 segundos e um webhook 20 segundos. O nome de uma automação pode ter até 120 caracteres. Um agente de IA tem as suas próprias definições: mensagens anteriores que lê, 0 a 40 (predefinição 20), resposta mais longa 100 a 4000 tokens (predefinição 800), até 10 chamadas de ferramentas por resposta (predefinição 5) e horas de passagem a uma pessoa, 1 a 168 (predefinição 24).

Pause on a chat after I answer it (hours)takeoverHours, 0 to 168, default 4. 0 turns the pause off; a reply still ends a waiting step.
AI replies per chat per hour, at mostaiMaxPerHour, 1 to 60, default 10, counted per chat in a one-hour window.
Earlier messages it readshistory, 0 to 20, default 10, from the messages kept for that chat.
Longest reply (tokens)maxTokens, 50 to 2,000, default 600. An answer that reaches it stops there.
The On and Off switchenabled, default true: a new automation saves On, in the editor and through create_automation.
Try itSamples of up to 2,000 characters, 60 tests per hour in the dashboard.

Que automação responde quando vários coincidem?

No máximo uma, escolhida por uma ordem fixa: primeiro Tem palavra-chave, depois Primeira mensagem, depois Fora de horas, depois Todas as mensagens, e dentro do mesmo tipo a automação mais antiga primeiro. Só competem as automações ativadas e não pausadas, por isso, quando a regra de palavra-chave está desativada, ou pausada por uma chave de IA recusada, a regra geral responde em seu lugar. Há duas consequências que surpreendem as pessoas. Um cliente novo que escreve à noite recebe a automação de Primeira mensagem, não a de Fora de horas, porque Primeira mensagem tem prioridade superior. E uma mensagem que uma automação de palavra-chave responde nunca chega a um agente de IA nem a um passo Responder com IA em Todas as mensagens, por isso coloque o agente ou o passo de IA dentro da automação de palavra-chave quando quiser ambos. Uma mensagem que responde a um passo Fazer uma pergunta aberto pertence a essa pergunta, e nenhuma outra automação começa com ela. As automações de etiqueta e de webhook começam pelos seus próprios eventos e não participam nesta ordem.

Que proteções estão incorporadas?

O motor aplica estas regras sem qualquer definição, e os motivos de ignorar no separador Execuções indicam-nas quando param uma execução:

  • Uma mensagem que a Meta entrega duas vezes inicia uma só execução: os duplicados são descartados pelo id da mensagem.
  • Reações, estados, os envios da própria automação e os ecos das mensagens enviadas a partir da aplicação nunca iniciam uma execução.
  • Responder com texto, Fazer uma pergunta, Enviar uma imagem ou ficheiro, 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 um template não.
  • Uma resposta escrita na app WhatsApp Business pausa a automação nessa conversa, e uma execução à espera ali ignora os passos restantes.
  • Uma nova mensagem que inicia a mesma automação numa conversa substitui a execução que ainda espera num passo Esperar; uma mensagem que responde a uma pergunta aberta vai antes para essa pergunta.
  • Os envios a partir de um número são espaçados de pelo menos 100 ms, abaixo dos 20 por segundo da Meta para números Coexistence.
  • Um passo falhado envia-lhe 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 esse fornecedor e envia um e-mail.

O que recebe a ferramenta create_automation?

O conector MCP tem dezanove ferramentas para automações e para 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 ficheiros: 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 é aceite. 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 deixar de fora, e steps, quando dado, 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». As chaves de IA nunca passam pelo MCP. No exemplo, a Espera de 1 minuto permite que um cliente que envia várias linhas de uma vez receba uma só resposta.

create_automation arguments: an after-hours AI assistant, saved Off to test first
{
  "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. «sim» também corresponde a «assim» e «simples», por isso a automação responde a mensagens para as quais não foi feita; use É exatamente, ou uma palavra-chave mais longa.
  • Listar só a grafia com acento. A correspondência ignora maiúsculas e minúsculas, mas não acentos, por isso «preço» não apanha clientes que escrevem «preco»; acrescente as duas.
  • Esperar que Primeira mensagem deixe de fora os clientes habituais. Dispara para qualquer cliente cuja conversa a easyCoexistence não viu nos últimos 30 dias, por isso clientes antigos recebem a mensagem de boas-vindas na primeira mensagem depois de a ativar.
  • Escolher um template que precisa de imagem de cabeçalho ou de um botão para copiar código. As automações preenchem apenas variáveis do corpo, por isso o editor lista-o mas não deixa escolhê-lo, e, se o definir por MCP, a Meta recusa o envio e a execução falha.
Fazer isto com a EasyCoexistence

A easyCoexistence executa estas automações no número WhatsApp Business que continua a usar na app, através da Cloud API da Meta e da Coexistence. Crie-as no editor, em Automações, Nova automação, ou deixe o ChatGPT ou o Claude chamar create_automation e test_automation pelo conector MCP, que tem mais de 30 ferramentas. De US$ 9 a US$ 0.75 por número ligado por mês, a descer à medida que acrescenta números, com os primeiros 3 dias grátis.

Perguntas frequentes

Uma automação pode ramificar-se conforme o que o cliente diz?

Sim. Dividir em caminhos (condition) ramifica pelo texto da mensagem, por um campo do contacto, por uma etiqueta, por uma resposta anterior de uma API ou pelo seu horário de funcionamento, e A IA escolhe o caminho (ai_decide) decide pelo significado, em qualquer língua, no seu próprio modelo. Cada caminho tem a sua própria linha de passos, e uma linha Caso contrário apanha o resto. Também pode entregar a decisão ao n8n ou ao seu backend com Chamar o meu webhook, que pode devolver um {"reply": "..."} diferente para cada caso.

Há limite de automações ou de execuções?

Não há limite de execuções nem custo extra por elas, e não há limite de automações por número. Os limites que se aplicam são por conversa: respostas de IA por hora, a regra das 24 horas da Meta para texto e a pausa depois de responder a partir do telemóvel.

Posso mover ou copiar uma automação para outro número?

Mova-a alterando a sua Ligação no editor, ou com update_automation e um novo connection_id; as execuções que ainda esperam no número antigo terminam como substituídas. Para copiar uma, peça à sua IA que a leia com list_automations e crie o mesmo gatilho e os mesmos passos no outro número.

O que acontece às execuções em espera quando edito uma automação?

Continuam. Uma execução parada numa Espera retoma no próximo número de passo da automação, tal como está guardada quando a execução acorda, por isso uma edição pode mudar o que envia. Para as parar, desative a automação: terminam então como Ignoradas, com o motivo «Automação desativada».

Continue a ler

Pronto para começar?

Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.

Começar período experimental gratuito

Verificado em