Documentatie
Sign inGet Started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

Trefwoordregels

Bird levert de trefwoordcatalogus mee, dus een ontvanger die STOP beantwoordt op een van je nummers met inkomende berichten is afgemeld zonder dat je iets hoeft in te stellen. START draait dat terug. Een eigen regel overschrijft de standaard van Bird voor het bereik dat die regel dekt.
Deze pagina behandelt wat Bird herkent, hoe een inkomend bericht wordt gematcht, en hoe je de bewoordingen wijzigt of trefwoorden toevoegt. De pagina Keywords is het equivalent in het dashboard.
Een lijst met trefwoordregels, met de werkruimteregels boven de standaardregels die ze overschrijven

Wat Bird standaard herkent

Negen woorden registreren een opt-out:
stop, stop all, stopall, unsubscribe, cancel, end, quit, revoke, optout
Twee draaien dat terug: start en unstop.
Matching gebeurt op het volledige bericht, niet op een substring. Omdat cancel en end trefwoorden zijn, maakt dat onderscheid uit: "cancel my 3pm delivery" is een gewoon bericht en geen intrekking van toestemming. Hoofdletters, accenten, herhaalde spaties en afsluitende leestekens worden genegeerd, dus Stop! en STOP matchen allebei. Leestekens vóór of in het woord worden niet genegeerd, dus #stop matcht niet.

Waar trefwoorden niet worden gematcht

Een trefwoord in een groepsbericht wordt overgeslagen, zodat een deelnemer zich niet kan afmelden door daar te antwoorden. Respecteer de opgegeven opt-out van een groepslid in je eigen verzendlogica.

Wanneer de voorkeur wordt vastgelegd

Classificatie loopt gelijktijdig met het whatsapp.received-event, niet ervoor. Een integratie die dat event bewaakt, kan daardoor een STOP zien binnenkomen voordat de voorkeur die het vastlegt bestaat. Als je handler op het inkomende bericht reageert door iets te verzenden, lees dan de records van de ontvanger opnieuw in plaats van de eventvolgorde als gegeven te beschouwen.

Bekijken wat van toepassing is

GET /v1/whatsapp/keyword-rules beschrijft hoe antwoorden op je nummers worden afgehandeld. Zonder filter geeft het de catalogus van Bird terug samen met eventuele regels die je hebt aangemaakt. Beperk de resultaten met country, waba, operation of scope:
  • scope=system geeft de catalogus van Bird terug, inclusief de standaard die een eigen regel overschrijft.
  • scope=workspace geeft je eigen regels terug.
const rules = await bird.whatsapp.keywordRules.list({ operation: "opt_out" });
for (const rule of rules.data ?? []) {
  console.log(rule.scope, rule.effective_keywords);
}
Regels komen terug van meest specifiek naar minst specifiek, wat de volgorde is waarin een inkomend bericht ertegen wordt gematcht. Elke regel bevat effective_keywords: de set van Bird voor die operatie en dat land, plus alles wat je hebt toegevoegd.
Bij een eigen regel zonder country toont effective_keywords de wereldwijde set van Bird, omdat de regel geen land heeft en dat van de afzender onbekend is totdat er een bericht binnenkomt. Die regel matcht tegen de set van Bird voor het land van de afzender, wat een grotere set kan zijn. Stel een country in op je regel om precies te zien wat die afzenders matchen.
country is het land van de afzender, afgeleid uit diens eigen telefoonnummer en niet uit het nummer waarnaar het bericht is gestuurd. Dit is het landsignaal dat WhatsApp meestuurt. Een afzender die wordt geïdentificeerd door een business-scoped user ID heeft geen land, dus een bericht van zo'n afzender slaat de landgebonden regels over en matcht in plaats daarvan een wereldwijde regel.

Het antwoord wijzigen

De standaardantwoorden van Bird zijn correct maar generiek. Om in je eigen naam te antwoorden, maak je een regel aan:
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);
Je regel vervangt het antwoord van Bird voor dat bereik en behoudt de trefwoorden van Bird. Je keywords zijn aanvullingen en geen vervanging, dus een trefwoord dat Bird later toevoegt begint direct te matchen zonder dat je iets hoeft aan te passen.
Om niets te verzenden maar de opt-out toch vast te leggen, laat je reply weg bij het aanmaken van de regel. Om een bestaande regel stil te zetten, stel je reply in op null in een JSON-body van de onderstaande update; een CLI-flag kan geen null bevatten.
Een dialoogvenster voor het toevoegen van een trefwoordregel, met velden voor extra trefwoorden en een antwoord

Eigen trefwoorden toevoegen

// 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);
Het weglaten van keywords laat je aanvullingen intact. Een lege array versturen wist ze terug naar de set van Bird.

Regelbereik en duplicaten

Een regel beperkt zich tot één WhatsApp Business Account met waba, tot één afzenderland met country, tot beide, of tot geen van beide. Je hebt één regel per combinatie van operatie, land en account. Een tweede schrijfactie voor dezelfde combinatie geeft een duplicaatfout.
Bird weigert een regel die stop aan opt_in koppelt, ongeacht of het woord uit de catalogus van Bird kwam of uit een van je andere regels, zodat een opt-outwoord niet kan worden gebruikt om toestemming te verlenen.

Een regel verwijderen

Het verwijderen van je regel draagt dat bereik over aan de volgende regel in de matchvolgorde, en dat is niet altijd een regel van jou. De volgorde is:
  1. Je regel voor een account en land.
  2. Je regel voor het account.
  3. Je regel voor het land.
  4. De regel van Bird voor het land van de afzender.
  5. Je wereldwijde regel.
  6. De wereldwijde regel van Bird.
Het verwijderen van je regel voor een land draagt het bereik daarom over aan de regel van Bird voor dat land, vóór je eigen wereldwijde regel:
// The next rule in the ladder answers the scope, which is another rule of yours if you hold a less specific one; STOP never stops working.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");
Het verwijderen van een regel stopt STOP niet. Het zet de bewoordingen en de trefwoordset terug naar de eerstvolgende regel in die volgorde.

Vervolgstappen

  • Voorkeuren: de records die een trefwoord aanmaakt, en welke daarvan je kunt terugdraaien.
  • Suppressies: de adressen die je werkruimte direct blokkeert.
  • Opt-outs en trefwoorden voor SMS: hetzelfde mechanisme op het andere kanaal, dat ook help- en campagnetrefwoorden ondersteunt.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsConnecting WhatsApp to Bird: from buying a number to a live channelBegrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builderOntdek de mogelijkheidWhatsApp
Probeer de oefening en ontvang een implementatieoverzicht