Sign inGet Started

Reguły słów kluczowych WhatsApp

Bird dostarcza katalog słów kluczowych, więc odbiorca, który odpowie STOP na jeden z Twoich numerów obsługujących wiadomości przychodzące, zostaje wypisany bez żadnej konfiguracji z Twojej strony. START cofa wypisanie. Własna reguła zastępuje domyślną regułę Bird w zakresie, którego dotyczy.

Ta strona opisuje, co rozpoznaje Bird, jak dopasowywana jest wiadomość przychodząca oraz jak zmienić treść odpowiedzi lub dodać słowa kluczowe. Odpowiednikiem w panelu jest strona Keywords.

Lista reguł słów kluczowych, w której reguły obszaru roboczego znajdują się nad zastępowanymi przez nie regułami domyślnymi

Co Bird rozpoznaje domyślnie

Dziewięć słów rejestruje wypisanie:

stop, stop all, stopall, unsubscribe, cancel, end, quit, revoke, optout

Dwa je cofają: start i unstop.

Dopasowanie dotyczy całej wiadomości, a nie jej fragmentu. Ta różnica ma znaczenie, ponieważ cancel i end są słowami kluczowymi: "cancel my 3pm delivery" to zwykła wiadomość, a nie wycofanie zgody. Wielkość liter, znaki diakrytyczne, powtórzone spacje i końcowa interpunkcja są ignorowane, więc dopasowane zostają zarówno Stop!, jak i STOP. Interpunkcja przed słowem lub wewnątrz niego nie jest ignorowana, więc #stop nie zostaje dopasowane.

Gdzie słowa kluczowe nie są dopasowywane

Słowo kluczowe w wiadomości grupowej jest pomijane, więc uczestnik nie może zrezygnować z subskrypcji, odpowiadając w grupie. Uwzględniaj zgłoszoną rezygnację członka grupy we własnej logice wysyłania.

Kiedy preferencja jest zapisywana

Klasyfikacja działa równolegle ze zdarzeniem whatsapp.received, a nie przed nim. Integracja obserwująca to zdarzenie może więc zobaczyć wiadomość STOP, zanim zapisywana przez nią preferencja zacznie istnieć. Jeśli Twój handler reaguje na wiadomość przychodzącą, wysyłając coś, odczytaj ponownie rekordy odbiorcy zamiast zakładać kolejność zdarzeń.

Sprawdzanie, co obowiązuje

GET /v1/whatsapp/keyword-rules opisuje, jak obsługiwane są odpowiedzi na Twoje numery. Bez filtrów zwraca jeden wiersz na zakres: Twoją regułę tam, gdzie ją masz, a regułę Bird tam, gdzie jej nie masz. Twoja reguła bez waba zastępuje regułę Bird dla tej samej operacji i kraju. Zawęź wynik za pomocą country, waba, operation lub scope:

  • scope=system zwraca katalog Bird, w tym regułę domyślną, którą zastępuje Twoja reguła.
  • scope=workspace zwraca Twoje własne reguły.
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}

Reguły są zwracane od najbardziej szczegółowej, czyli w kolejności, w jakiej dopasowywana jest do nich wiadomość przychodząca. Każda zawiera effective_keywords: zestaw Bird dla danej operacji i kraju, bez słów, które usunięto, i z tymi, które dodano.

W przypadku Twojej reguły bez country pole effective_keywords pokazuje ogólnoświatowy zestaw Bird, ponieważ reguła nie ma kraju, a kraj nadawcy jest nieznany do chwili nadejścia wiadomości. Ta reguła jest dopasowywana do zestawu Bird dla kraju nadawcy, który może być większy. Ustaw country w swojej regule, aby zobaczyć, do czego dokładnie dopasowywane są wiadomości tych nadawców.

country to kraj nadawcy, ustalany na podstawie jego własnego numeru telefonu, a nie numeru, na który napisał. To sygnał kraju wysyłany przez WhatsApp. Nadawca identyfikowany przez identyfikator użytkownika o zakresie firmowym nie ma kraju, więc jego wiadomość pomija reguły przypisane do krajów i jest dopasowywana do reguły ogólnoświatowej.

Zmiana odpowiedzi

Domyślne odpowiedzi Bird są poprawne, ale ogólne. Aby odpowiadać we własnym imieniu, utwórz regułę:

const rule = await bird.whatsapp.keywordRules.create({
  operation: "opt_out",
  country: "US", // the SENDER's country, from their own number
  reply: "You're off the list. ACME Courier won't message you again.",
});
// effective_keywords is Bird's set plus any of your own.
console.log(rule.id, rule.effective_keywords);

Twoja reguła zastępuje odpowiedź Bird dla tego zakresu i zachowuje słowa kluczowe Bird. Twoje keywords są dodatkami, a nie zamiennikiem, więc słowo kluczowe, które Bird doda później, zaczyna działać bez żadnych zmian z Twojej strony.

Aby niczego nie wysyłać, a nadal rejestrować rezygnację, pomiń reply podczas tworzenia reguły. Aby wyciszyć istniejącą regułę, ustaw reply na null w treści JSON w poniższej aktualizacji; flaga CLI nie może przenosić null.

Okno reguły słów kluczowych z listą słów kluczowych Bird, dodanym słowem kluczowym, usuniętym słowem kluczowym i odpowiedzią

Dodawanie własnych słów kluczowych

// Omitting keywords leaves the set alone; an empty array clears your additions
// back to Bird's. reply: null switches the auto-reply off and still records
// the opt-out.
const rule = await bird.whatsapp.keywordRules.update("wkr_01m2kj8x4te9p0rr7e5w2n1abc", {
  keywords: ["no more texts", "remove me"],
});
console.log(rule.effective_keywords);

Pominięcie keywords pozostawia Twoje dodatki bez zmian. Wysłanie pustej tablicy usuwa je i przywraca zestaw Bird.

Usuwanie słów kluczowych Bird

Niektóre rozmowy wymagają cancel lub stop jako zwykłych słów, na przykład w przepływie bota, w którym cancel oznacza anulowanie bieżącego kroku. Wymień je w excluded_keywords w swojej regule:

Przykład kodu
curl -X POST https://us1.platform.bird.com/v1/whatsapp/keyword-rules \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation":"opt_out","waba":"102290129340398","excluded_keywords":["cancel","end"]}'

Wiadomość składająca się dokładnie z jednego z nich nie powoduje wtedy niczyjej rezygnacji i nie otrzymuje odpowiedzi w przypadku osób objętych regułą. Wiadomość nadal dociera do Ciebie jak zwykle, a własna reguła Bird nie obsługuje jej zamiast Twojej. Wyklucz wszystkie słowa kluczowe Bird, aby je wyłączyć. Słowo kluczowe, które Bird doda później, nadal będzie dopasowywane, chyba że Twoja reguła już je wyklucza. Po usunięciu słów kluczowych sam odpowiadasz za respektowanie rezygnacji, które one wyrażają. Własny przycisk rezygnacji Meta w szablonach marketingowych nadal działa.

Przy aktualizacji excluded_keywords zastępuje zestaw usuniętych słów, pusta tablica nie usuwa żadnego, a pominięcie pola pozostawia zestaw bez zmian. Słowa kluczowego nie można jednocześnie dodać i wykluczyć. Każde wykluczone słowo kluczowe musi być jednym ze słów kluczowych Bird dla operacji reguły. W przypadku reguły z country musi to być jedno ze słów kluczowych Bird dla tego kraju albo jedno z ogólnoświatowych słów kluczowych Bird, jeśli Bird nie ma słów dla tego kraju. Bird odrzuca każde inne słowo z 422, ponieważ w przeciwnym razie usunęłoby to słowo, gdyby Bird dodał je później.

Zakres reguły i duplikaty

Regułę można zawęzić do jednego konta WhatsApp Business Account za pomocą waba, do jednego kraju nadawcy za pomocą country, do obu naraz albo do żadnego. Możesz mieć jedną regułę na każdą kombinację operacji, kraju i konta. Drugi zapis dla tej samej kombinacji zwraca błąd duplikatu.

Bird odrzuca regułę, która wiąże stop z opt_in, niezależnie od tego, czy słowo pochodzi z katalogu Bird, czy z innej Twojej reguły, dzięki czemu słowa rezygnacji nie da się użyć do udzielenia zgody.

Usuwanie reguły

Po usunięciu Twojej reguły dany zakres przejmuje następna reguła w kolejności dopasowania, która nie zawsze jest Twoja. Kolejność jest następująca:

  1. Twoja reguła dla konta i kraju.
  2. Twoja reguła dla konta.
  3. Twoja reguła dla kraju.
  4. Reguła Bird dla kraju nadawcy.
  5. Twoja reguła globalna.
  6. Globalna reguła Bird.

Dlatego po usunięciu Twojej reguły dla kraju zakres przejmuje reguła Bird dla tego kraju, a nie Twoja reguła globalna:

// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");

Po usunięciu reguły treść odpowiedzi i zestaw słów kluczowych wracają do tej reguły, która jest następna w tej kolejności. Jeśli jest to Twoja reguła wykluczająca stop, to STOP również tam nic nie robi.

Kolejne kroki

  • Preferencje: rekordy tworzone przez słowo kluczowe oraz to, które z nich możesz cofnąć.
  • Suppresje: adresy, które Twój obszar roboczy blokuje bezpośrednio.