Dokumentacja automatyzacji WhatsApp: wyzwalacze, kroki, zmienne i limity
Automatyzacje easyCoexistence na numerze WhatsApp startują od przychodzącej wiadomości, od kontaktu, który dostaje tag, albo od wywołania z Twojego systemu. Wiadomość ma cztery dopasowania: Każda wiadomość, Zawiera słowo kluczowe, Pierwsza wiadomość i Poza godzinami pracy. Dalej idą kroki, do 30 w jednej linii i 60 łącznie, z rozgałęzieniami, pytaniami i agentami AI. Jedna wiadomość uruchamia najwyżej jedną automatyzację, a reguły ze słowami kluczowymi są sprawdzane jako pierwsze.
Kroków w jednej linii, 60 łącznie, rozgałęzienia zagnieżdżone na 4 poziomy; Zatrzymaj i Wróć do kroku mogą tylko kończyć linię.
Na automatyzację, do 100 znaków na każde słowo kluczowe; wystarczy jedno trafienie, a wielkość liter nie ma znaczenia.
Dozwolone znaki w instrukcji kroku Odpowiedz z AI; odpowiedzi są ograniczone do 50 do 2,000 tokenów.
Najdłuższy pojedynczy krok Czekaj to 23 godziny, dzięki czemu kolejny krok tekstowy wciąż mieści się w 24-godzinnym oknie Meta.
Czas, w którym webhook musi odpowiedzieć, zanim krok Wywołaj mój webhook zakończy się błędem; pole reply w odpowiedzi trafia do klienta.
Przechowywanie przebiegów, z każdą wiadomością startową i odpowiedzią; tekst wiadomości jest usuwany po okresie przechowywania, który wybierzesz (30, 90 lub 365 dni, domyślnie 90).
Których wyzwalaczy i dopasowań może użyć automatyzacja WhatsApp?
Główny wyzwalacz, „Przychodzi wiadomość” (message_received), uruchamia się, gdy klient napisze na numer: tekst, zdjęcia, wideo, dokumenty, nagrania audio, naklejki, lokalizacje, wizytówki, odpowiedzi przyciskami i z listy oraz zamówienia. Wiadomość głosowa jest zamieniana na tekst na Twoim kluczu OpenAI lub OpenRouter i zapisywana jako „[voice message]” z następującymi po nim słowami, które może dopasować słowo kluczowe; bez takiego klucza pozostaje „[voice message]”. Reakcje, statusy i komunikaty systemowe nigdy nie uruchamiają przebiegu, a czaty grupowe nie docierają do API na numerze Coexistence. Dwa kolejne wyzwalacze nie startują od wiadomości. „Kontakt dostaje tag” (tag_added) uruchamia się za każdym razem, gdy kontakt dostępny na numerze dostanie wskazany przez Ciebie tag, z przepływu, od agenta AI, od Ciebie w Rozmowach lub przez update_contact. „Twój system wywołuje adres URL” (webhook_received) uruchamia się, gdy Twój własny system wyśle POST z JSON-em zawierającym numer telefonu na adres URL automatyzacji, z sekretem automatyzacji jako tokenem Bearer, na przykład przy nowym zamówieniu lub rezerwacji; treść żądania, do 20 KB, jest dostępna jako {{vars.webhook.*}}. W obu {{message}} jest puste, a osoba, która nie napisała w ciągu ostatnich 24 godzin, może dostać tylko send_template. Nie ma wyzwalacza czasowego. W wyzwalaczu wiadomości Poza godzinami pracy traktuje dni zaznaczone w polu „Otwarte w dniach” jako otwarte między Od a Do, w strefie IANA, na przykład America/Sao_Paulo. Gdy Do jest wcześniej niż Od, mamy zmianę nocną (22:00 do 06:00), a niezaznaczony dzień jest traktowany jako zamknięty przez cały dzień. W API godziny przyjmują pola timezone, days (1 = poniedziałek do 7 = niedziela, dni otwarcia) oraz start i end. Pierwsza wiadomość uruchamia się, gdy easyCoexistence zakłada rekord dla czatu: pierwsza wiadomość klienta od włączenia automatyzacji na numerze, także u dawnych klientów, albo pierwsza po 30 dniach ciszy. Czat otwarty z telefonu już liczy się jako widziany.
Jak działają tryby dopasowania słów kluczowych?
W polu „Gdzie ma stać słowo” opcja Zawiera („Gdziekolwiek w wiadomości”) jest domyślna, Zaczyna się od to „Na początku”, a Jest dokładnie to „Cała wiadomość”. W API keywordMode przyjmuje wartości contains, starts_with albo exact. Dopasowanie pomija spacje wokół wiadomości i ignoruje wielkość liter, ale nie ignoruje akcentów ani interpunkcji, a Zawiera trafia także w dłuższe słowa. Pole „Przetestuj” pod słowami kluczowymi odpowiada „Uruchomi się: pasuje” z danym słowem albo „Nie uruchomi się: żadne słowo kluczowe nie pasuje” dla dowolnego przykładu, który wpiszesz.
| 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? |
Co robi każdy krok i jakie pola przyjmuje?
Kroki działają od góry do dołu, do 30 w jednej linii i 60 w automatyzacji, wliczając rozgałęzienia, a przynajmniej jeden musi robić coś więcej poza Czekaj, Zatrzymaj, Podziel na ścieżki, AI wybiera ścieżkę i Wróć do kroku. Krok rozgałęziający ma jedną linię kroków dla każdej ścieżki oraz linię W przeciwnym razie, a rozgałęzienia można zagnieżdżać na 4 poziomy. W menu „Wybierz krok” każdy pokazuje nazwę i krótki opis, oba przytoczone poniżej dla sześciu podstawowych kroków. Zadaj pytanie (ask) wysyła swoją Wiadomość z maksymalnie 10 przyciskami, z których 3 są widoczne jako przyciski do stuknięcia, a pozostałe są wypisane na liście i wybiera się je numerem, czeka na odpowiedź do 1380 minut i zapisuje ją w polu kontaktu jako tekst, e-mail, liczbę, telefon lub jeden z przycisków; po błędnej odpowiedzi pytanie jest zadawane ponownie, do 3 razy. Odpowiedź agenta (agent) przekazuje wiadomość jednemu z Twoich agentów AI, Wyślij obraz lub plik (send_file) wysyła obraz lub PDF z Twoich plików, a Przekaż człowiekowi (handoff) wstrzymuje bota na tym czacie na od 1 do 168 godzin, domyślnie 24, i wysyła Ci e-mail. Podziel na ścieżki (condition) i AI wybiera ścieżkę (ai_decide) rozgałęziają według reguł lub według znaczenia. AI zapisuje szczegóły (ai_extract), Zapisz w kontakcie (set_field) i Tag (tag) zapisują pola kontaktu i tagi, a Wywołaj API (http_request) wywołuje dowolne API przez HTTPS i zachowuje jego odpowiedź JSON jako {{vars.<name>...}}. Uruchom automatyzację (start_automation) uruchamia inną automatyzację dla tej samej osoby, najwyżej na 3 poziomy w głąb, Wróć do kroku (goto) przeskakuje do identyfikatora kroku, aby utworzyć pętlę, a Powiadom mnie (notify_owner) wysyła Ci e-mail, najwyżej 20 na godzinę na automatyzację. Jeśli krok się nie powiedzie, kolejne kroki są pomijane, a przebieg kończy się statusem Błąd. Wywołaj mój webhook wysyła żądanie POST w formacie JSON z event „automation.step”, dry_run, run_id, numerem, kontaktem (wa_id, name), wiadomością (id, type, text, at) i do 10 ostatnich wiadomości czatu. Podpis znajduje się w nagłówku X-EC-Signature jako t=<unix>,v1=<HMAC-SHA256 z „<t>.<body>”> kluczem „Sekret podpisu” danego kroku. Adres URL musi być publiczny (HTTPS), a przekierowania nie są śledzone.
Których zmiennych mogą używać kroki?
Cztery są wypełniane na podstawie wiadomości, która rozpoczęła przebieg, i zapisuje się je w podwójnych nawiasach klamrowych; {{contact.<field>}} dodaje pole kontaktu (także contact.name i contact.phone), a {{vars.<path>}} to, co zapisały wcześniejsze kroki, na przykład odpowiedź kroku Wywołaj API. Działają w polu Wiadomość kroku Odpowiedz tekstem, w zmiennych treści szablonu, w instrukcji kroku Odpowiedz z AI oraz w tekście innych kroków, takich jak Zadaj pytanie. W zmiennych szablonu przyciski „Wstaw:” dodają je jednym kliknięciem. Wartość nieznana, na przykład profil bez nazwy, staje się pusta. Wysyłki szablonów przenoszą wyłącznie zmienne treści, po pozycji, więc szablonu z nazwanymi zmiennymi, obrazem lub zmienną w nagłówku albo przyciskiem ze zmienną nie da się jeszcze wybrać, a pusta zmienna sprawia, że Meta odrzuca wysyłkę.
- {{
first_name}}: pierwsze słowo nazwy profilu klienta w WhatsApp („Imię”). - {{name}}: pełna nazwa profilu („Pełna nazwa”).
- {{message}}: tekst wiadomości albo jej zastępnik, na przykład „[image]”, wraz z podpisem („Wiadomość klienta”).
- {{phone}}: numer klienta w formacie międzynarodowym, same cyfry bez plusa, na przykład 5511999998888 („Telefon klienta”).
- W teście klientem jest „Testowy klient”, a telefon to 15550000000.
Jakie są ustawienia i ich wartości domyślne?
Dwa ustawienia znajdują się w sekcji „Zaawansowane”, czyli w przycisku obok przełącznika „Włączona” w edytorze, a krok AI ma dwa własne. Pominięte pole przyjmuje wartość domyślną, zarówno w edytorze, jak i przez create_automation. Limity czasu są stałe, a nie ustawiane: odpowiedź AI ma 45 sekund, a webhook 20 sekund. Nazwa automatyzacji może mieć do 120 znaków. Agent AI ma własne ustawienia: liczba wcześniejszych wiadomości, które czyta, od 0 do 40 (domyślnie 20), najdłuższa odpowiedź od 100 do 4000 tokenów (domyślnie 800), do 10 wywołań narzędzi na odpowiedź (domyślnie 5) oraz godziny przekazania człowiekowi, od 1 do 168 (domyślnie 24).
Która automatyzacja odpowie, gdy pasuje kilka?
Najwyżej jedna, wybrana w stałej kolejności: najpierw Zawiera słowo kluczowe, potem Pierwsza wiadomość, potem Poza godzinami pracy, a na końcu Każda wiadomość. W obrębie tego samego rodzaju pierwsza jest najstarsza automatyzacja. Biorą udział tylko automatyzacje Włączone i niewstrzymane, więc gdy reguła słowa kluczowego jest wyłączona albo wstrzymana przez odrzucony klucz AI, zamiast niej odpowiada ogólna automatyzacja. Dwie konsekwencje zaskakują. Nowy klient, który napisze w nocy, dostanie automatyzację Pierwsza wiadomość, a nie Poza godzinami pracy, bo Pierwsza wiadomość ma wyższy priorytet. Wiadomość obsłużona przez automatyzację ze słowem kluczowym nigdy nie trafia do agenta AI ani do kroku Odpowiedz z AI w automatyzacji Każda wiadomość, więc jeśli chcesz oba, umieść agenta lub krok AI wewnątrz automatyzacji ze słowem kluczowym. Wiadomość, która odpowiada na otwarty krok Zadaj pytanie, należy do tego pytania i żadna inna automatyzacja się na niej nie uruchamia. Automatyzacje z tagiem i webhookiem uruchamiają się od własnych zdarzeń i nie biorą udziału w tej kolejności.
Jakie zabezpieczenia są wbudowane?
Runner stosuje je bez żadnego ustawienia, a powody pominięcia w zakładce Przebiegi wskazują je, gdy zatrzymują przebieg:
- Wiadomość, którą Meta dostarcza dwukrotnie, uruchamia jeden przebieg: duplikaty są odrzucane po identyfikatorze wiadomości.
- Reakcje, statusy, własne wysyłki automatyzacji i echa Twoich wiadomości z aplikacji nigdy nie uruchamiają przebiegu.
- Odpowiedz tekstem, Zadaj pytanie, Wyślij obraz lub plik, Odpowiedz z AI, odpowiedź agenta i odpowiedź webhooka wymagają, by ostatnia wiadomość klienta była młodsza niż 24 godziny; Wyślij szablon tego nie wymaga.
- Odpowiedź wpisana w aplikacji WhatsApp Business wstrzymuje automatyzację w tym czacie, a przebieg czekający w nim pomija pozostałe kroki.
- Nowsza wiadomość, która uruchamia tę samą automatyzację na tym czacie, zastępuje przebieg, który wciąż czeka w kroku Czekaj; wiadomość, która odpowiada na otwarte pytanie, trafia zamiast tego do tego pytania.
- Wysyłki z numeru są odstępowane co najmniej o 100 ms, poniżej limitu Meta wynoszącego 20 na sekundę dla numerów Coexistence.
- Nieudany krok wysyła e-mail, najwyżej raz na automatyzację co 6 godzin; odrzucony klucz AI wstrzymuje automatyzacje korzystające z tego dostawcy i wysyła jeden e-mail.
Co przyjmuje narzędzie create_automation?
Łącznik MCP ma dziewiętnaście narzędzi do automatyzacji i tego, z czego korzystają. Osiem służy do automatyzacji: set_inbound_mode, list_automations, create_automation, update_automation, delete_automation, test_automation, list_automation_runs i get_automation_run. Osiem służy do agentów i plików: list_agents, list_files, create_agent, update_agent, delete_agent, add_agent_knowledge, delete_agent_knowledge i test_agent. Trzy służą do pracy z ludźmi: list_conversations, get_conversation i update_contact. create_automation przyjmuje connection_id (z list_numbers), name, enabled, trigger, steps i settings, w snake_case, na przykład keyword_mode i max_tokens; camelCase jest również akceptowany. Obiekty kroków to reply_text {text}, send_template {name, language, params}, ai_reply {provider, model, prompt, history, max_tokens}, call_webhook {url} i wait {minutes}, a dalej 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} i stop. update_automation zachowuje pola, których nie podasz, a steps, jeśli je podasz, zastępuje całą listę. Błędy wskazują pole, na przykład „trigger.keywords: Add at least one keyword”, „steps.2: Stop must be the last step of its line” albo „steps.0: save your openai API key on the Automations page first”. Klucze AI nigdy nie przechodzą przez MCP. W przykładzie 1-minutowe Czekaj sprawia, że klient, który wysyła kilka linijek naraz, dostaje jedną odpowiedź.
{
"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 }
}Typowe błędy
- Użycie dwuliterowego słowa kluczowego w trybie Zawiera. „oi” pasuje też do „noite” i „boi”, więc automatyzacja odpowiada na wiadomości, do których nie była przeznaczona. Użyj trybu Jest dokładnie albo dłuższego słowa.
- Podanie tylko wersji z akcentami. Dopasowanie ignoruje wielkość liter, ale nie akcenty, więc „preço” nie łapie klientów, którzy wpiszą „preco”. Dodaj obie wersje.
- Oczekiwanie, że Pierwsza wiadomość pominie stałych klientów. Uruchamia się ona dla każdego klienta, którego czat easyCoexistence nie widział przez 30 dni, więc dawni klienci dostaną powitanie przy pierwszej wiadomości po jej włączeniu.
- Wybór szablonu, który wymaga obrazu w nagłówku albo przycisku kopiowania kodu. Automatyzacje wypełniają tylko zmienne treści, więc edytor pokaże szablon na liście, ale nie pozwoli go wybrać. Ustawiony przez MCP zostanie odrzucony przez Meta, a przebieg zakończy się błędem.
easyCoexistence uruchamia te automatyzacje na numerze WhatsApp Business, którego używasz w aplikacji, przez Cloud API Meta i tryb Coexistence. Twórz je w edytorze w sekcji Automatyzacje, Nowa automatyzacja, albo pozwól ChatGPT lub Claude wywołać create_automation i test_automation przez łącznik MCP, który ma ponad 30 narzędzi. Od US$ 9 do US$ 0.75 za numer miesięcznie, im więcej numerów, tym taniej, z pierwszymi 3 dniami za darmo.
Najczęściej zadawane pytania
Czy automatyzacja może rozgałęziać się w zależności od tego, co napisze klient?
Tak. Podziel na ścieżki (condition) rozgałęzia według treści wiadomości, pola kontaktu, tagu, wcześniejszej odpowiedzi API lub Twoich godzin otwarcia, a AI wybiera ścieżkę (ai_decide) wybiera według znaczenia, w dowolnym języku, na Twoim własnym modelu. Każda ścieżka ma własną linię kroków, a linia W przeciwnym razie obsługuje resztę. Możesz też przekazać decyzję n8n lub własnemu backendowi przez Wywołaj mój webhook, który może zwrócić inne {"reply": "..."} dla każdego przypadku.
Czy są limity automatyzacji albo przebiegów?
Nie ma limitu przebiegów ani dodatkowej opłaty za nie, ani limitu liczby automatyzacji na numer. Obowiązują limity na czat: odpowiedzi AI na godzinę, 24-godzinna zasada Meta dla wiadomości tekstowych oraz pauza po odpowiedzi z telefonu.
Czy mogę przenieść albo skopiować automatyzację na inny numer?
Przenosisz ją, zmieniając jej Połączenie w edytorze albo przez update_automation z nowym connection_id. Przebiegi wciąż czekające na starym numerze kończą się jako zastąpione. Aby skopiować automatyzację, poproś AI, by odczytało ją przez list_automations i utworzyło te same wyzwalacze i kroki na innym numerze.
Co dzieje się z czekającymi przebiegami, gdy edytuję automatyzację?
Działają dalej. Przebieg zatrzymany na kroku Czekaj wznawia się od następnego numeru kroku w zapisanej wersji automatyzacji w chwili wybudzenia, więc edycja może zmienić to, co zostanie wysłane. Aby je zatrzymać, wyłącz automatyzację. Wtedy kończą się statusem Pominięte z komunikatem "Automation is off".
Czytaj dalej
Gotowy, aby zacząć?
Skonfiguruj WhatsApp Coexistence w kilka minut, nie miesięcy. Aplikacja nadal działa na telefonie.
Rozpocznij bezpłatny okres próbnyZweryfikowano w