Log inStart Free Trial
Meta Tech Provider

WhatsApp automation reference: triggers, steps, variables and limits

easyCoexistence automations on a WhatsApp number start from a message that arrives, a contact who gets a tag, or a call from your system. A message has four matches: Every message, Has keyword, First message and After hours. Then come steps, up to 30 in a line and 60 in all, with branches, questions and AI agents. A message gets at most one automation, keyword rules first.

30 steps

Steps in one line, 60 in all, branches nested 4 deep; Stop and Go back to a step can only end a line.

30 keywords

Per automation, up to 100 characters each; any one is enough, and capital letters do not matter.

20,000

Characters allowed in the Instructions of a Reply with AI step, whose answers are capped at 50 to 2,000 tokens.

1,380 min

Longest single Wait step, 23 hours, so the next text step still falls inside Meta's 24-hour window.

20 seconds

Time your webhook has to answer before Call my webhook fails; a reply field in the answer is sent to the customer.

30 days

Run retention, with each starting message and reply; message text goes after the retention you pick (30, 90 or 365 days, default 90).

Which triggers and matches can a WhatsApp automation use?

The main trigger, "A message arrives" (message_received), fires when a customer writes to the number: text, photos, video, documents, audio, stickers, locations, contact cards, button and list replies, and orders. A voice note is written out on your OpenAI or OpenRouter key and stored as "[voice message]" followed by the words, which a keyword can match; without such a key it stays "[voice message]". Reactions, statuses and system notices never start a run, and group chats do not reach the API on a Coexistence number. Two more triggers do not start from a message. "A contact gets a tag" (tag_added) fires each time a contact reachable on the number gets the tag you name, from a flow, an AI agent, you in Conversations or update_contact. "Your system calls a URL" (webhook_received) fires when your own system POSTs JSON with a phone number to the automation's URL, with the automation's secret as a Bearer token, for a new order or a booking; the body, up to 20 KB, is available as {{vars.webhook.*}}. In both, {{message}} is empty and a person who has not written in the last 24 hours can only get a send_template. There is no schedule trigger. On the message trigger, After hours treats the days ticked under "Open on" as open between From and To, in an IANA timezone such as America/Sao_Paulo; a To earlier than From is an overnight shift (22:00 to 06:00), and an unticked day counts as closed all day. In the API, hours takes timezone, days (1 = Monday to 7 = Sunday, the days you are open), and start and end. First message fires when easyCoexistence starts a record for the chat: a customer's first message since an automation was switched on for the number, long-time customers included, or the first one after 30 quiet days. A chat you opened from the phone already counts as seen.

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.

How do the keyword modes match?

Under "Where the word has to be", Contains ("Anywhere in the message") is the default, Starts with is "At the start" and Is exactly is "The whole message"; in the API, keywordMode is contains, starts_with or exact. Matching trims the spaces around the message and ignores capital letters, but it does not ignore accents or punctuation, and Contains also matches inside longer words. The "Test it" box under Keywords answers "Runs: it matches" with the keyword, or "Does not run: no keyword matches", for any sample you type.

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?

What does each step do, and which fields does it take?

Steps run top to bottom, up to 30 in a line and 60 in an automation, branches included, and at least one must do something besides Wait, Stop, Split into paths, AI picks the path and Go back to a step. A branching step holds a line of steps per path plus an Otherwise line, and branches nest 4 deep. In the "Choose a step" menu each one shows a name and a short line, both quoted below for the six basic steps. Ask a question (ask) sends its Message with up to 10 buttons, of which 3 show as tappable buttons and more are listed and answered by number, waits up to 1,380 minutes for the answer and saves it in a contact field as text, email, number, phone or one of the buttons; a wrong answer gets the question again up to 3 times. Agent answers (agent) hands the message to one of your AI agents, Send a picture or file (send_file) sends a picture or PDF from your files, and Hand to a person (handoff) pauses the bot on that chat for 1 to 168 hours, 24 by default, and emails you. Split into paths (condition) and AI picks the path (ai_decide) branch by rules or by meaning. AI saves details (ai_extract), Save to contact (set_field) and Tag (tag) write contact fields and tags, and Call an API (http_request) calls any HTTPS API and keeps its JSON answer as {{vars.<name>...}}. Start automation (start_automation) runs another automation for the same person, 3 deep at most, Go back to a step (goto) jumps to a step id to loop, and Notify me (notify_owner) emails you, at most 20 an hour per automation. If a step fails, the steps after it are skipped and the run ends Failed. Call my webhook POSTs JSON with event "automation.step", dry_run, run_id, the number, the contact (wa_id, name), the message (id, type, text, at) and up to 10 recent messages of the chat, signed in X-EC-Signature as t=<unix>,v1=<HMAC-SHA256 of "<t>.<body>"> with the step's "Signing secret". Its URL must be public HTTPS, and redirects are not followed.

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.

Which variables can steps fill in?

Four are filled from the message that started the run, written in double braces; {{contact.<field>}} adds a contact field (also contact.name and contact.phone) and {{vars.<path>}} what earlier steps saved, such as the answer of a Call an API step. They work in the Message of Reply with text, in a template's body variables, in the Instructions of Reply with AI and in the text of other steps such as Ask a question; in a template's variables, the "Insert:" chips add them. A value that is unknown, such as a profile with no name, becomes empty. Template sends carry body variables only, by position, so a template with named variables, a header picture or header variable, or a button with a variable cannot be picked yet, and a variable left empty makes Meta refuse the send.

  • {{first_name}}: the first word of the customer's WhatsApp profile name ("First name").
  • {{name}}: the full profile name ("Full name").
  • {{message}}: the text of the message, or its placeholder such as "[image]" plus the caption ("Their message").
  • {{phone}}: the customer's number as international digits without a plus, such as 5511999998888 ("Their phone").
  • In a test, the customer is "Test customer" and the phone is 15550000000.

What are the settings and their defaults?

Two settings sit under "Advanced", the button beside the On switch in the editor, and the AI step carries two more of its own. A field left out takes its default, in the editor and through create_automation alike. Timeouts are fixed rather than set: an AI reply gets 45 seconds and a webhook 20 seconds. An automation's name takes up to 120 characters. An AI agent has its own settings: earlier messages it reads, 0 to 40 (default 20), longest reply 100 to 4,000 tokens (default 800), up to 10 tool calls per answer (default 5) and hand-off hours, 1 to 168 (default 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.

Which automation answers when several match?

At most one, chosen in a fixed order: Has keyword first, then First message, then After hours, then Every message, and the oldest automation first within the same kind. Only automations that are On and not paused compete, so when the keyword rule is Off, or paused by a refused AI key, the catch-all answers instead. Two consequences surprise people. A new customer who writes at night gets the First message automation, not the After hours one, because First message ranks higher. And a message a keyword automation answers never reaches an AI agent or a Reply with AI step on Every message, so put the agent or the AI step inside the keyword automation when you want both. A message that answers an open Ask a question step belongs to that question, and no other automation starts on it. Tag and webhook automations start from their own events and take no part in this order.

Which guards are built in?

The runner applies these without any setting, and the skip reasons in the Runs tab name them when they stop a run:

  • A message Meta delivers twice starts one run: duplicates are dropped by message id.
  • Reactions, statuses, the automation's own sends and your echoes from the app never start a run.
  • Reply with text, Ask a question, Send a picture or file, Reply with AI, an agent's answer and a webhook's reply need the customer's last message to be under 24 hours old; Send a template does not.
  • A reply you type in the WhatsApp Business app pauses the automation on that chat, and a run waiting there skips its remaining steps.
  • A newer message that starts the same automation on a chat replaces the run still waiting in a Wait step; a message that answers an open question goes to that question instead.
  • Sends from a number are spaced at least 100 ms apart, under Meta's 20 per second for Coexistence numbers.
  • A failed step emails you, at most once per automation every 6 hours; a refused AI key pauses the automations using that provider and sends one email.

What does the create_automation tool take?

The MCP connector has nineteen tools for automations and what they use. Eight are for automations: set_inbound_mode, list_automations, create_automation, update_automation, delete_automation, test_automation, list_automation_runs and get_automation_run. Eight are for agents and files: list_agents, list_files, create_agent, update_agent, delete_agent, add_agent_knowledge, delete_agent_knowledge and test_agent. Three are for people: list_conversations, get_conversation and update_contact. create_automation takes connection_id (from list_numbers), name, enabled, trigger, steps and settings, in snake_case such as keyword_mode and max_tokens; camelCase is accepted too. The step objects are reply_text {text}, send_template {name, language, params}, ai_reply {provider, model, prompt, history, max_tokens}, call_webhook {url} and wait {minutes}, then 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} and stop. update_automation keeps the fields you leave out, and steps, when given, replace the whole list. Errors name the field, such as "trigger.keywords: Add at least one keyword", "steps.2: Stop must be the last step of its line" or "steps.0: save your openai API key on the Automations page first". AI keys never travel through MCP. In the example, the 1-minute Wait lets a customer who sends several lines at once get one answer.

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 }
}

Common mistakes

  • Using a two-letter keyword with Contains. "oi" also matches "noite" and "boi", so the automation answers messages it was never meant for; use Is exactly, or a longer keyword.
  • Listing only the accented spelling. Matching ignores capital letters but not accents, so "preço" misses customers who type "preco"; add both.
  • Expecting First message to skip regulars. It fires for any customer whose chat easyCoexistence has not seen in 30 days, so long-time customers get the welcome on their first message after you switch it on.
  • Choosing a template that needs a header picture or a copy-code button. Automations fill body variables only, so the editor lists it but will not let you pick it, and set through MCP the send is refused by Meta and the run fails.
Doing this with EasyCoexistence

easyCoexistence runs these automations on the WhatsApp Business number you keep using in the app, through Meta's Cloud API and Coexistence. Build them in the editor under Automations, New automation, or let ChatGPT or Claude call create_automation and test_automation through the MCP connector, which has more than 30 tools. US$ 9 down to US$ 0.75 per number per month, falling as you add numbers, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

Can an automation branch on what the customer says?

Yes. Split into paths (condition) branches on the message text, a contact field, a tag, an earlier API answer or your opening hours, and AI picks the path (ai_decide) chooses by meaning, in any language, on your own model. Each path holds its own line of steps, and an Otherwise line catches the rest. You can also hand the decision to n8n or your backend with Call my webhook, which can return a different {"reply": "..."} for each case.

Is there a limit on automations or runs?

There is no cap on runs and no extra charge for them, and no limit on how many automations a number has. The limits that apply are per chat: AI replies per hour, Meta's 24-hour rule for text, and the pause after you answer from the phone.

Can I move or copy an automation to another number?

Move it by changing its Connection in the editor, or with update_automation and a new connection_id; runs still waiting on the old number end as superseded. To copy one, ask your AI to read it with list_automations and create the same trigger and steps on the other number.

What happens to waiting runs when I edit an automation?

They carry on. A run parked on a Wait resumes at the next step number of the automation as it is saved when the run wakes up, so an edit can change what it sends. To stop them, switch the automation Off: they then end Skipped with "Automation is off".

Keep reading

Ready to get started?

Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.

Start Free Trial

Verified on