Sign inGet Started

Trefwoordregels van WhatsApp

Bird levert de trefwoordcatalogus mee. Een ontvanger die STOP antwoordt op een van je nummers die inkomende berichten ontvangen, wordt dus afgemeld zonder dat je iets hoeft in te stellen. START draait dat terug. Een eigen regel gaat voor de standaard van Bird binnen het bereik dat die regel dekt.

Deze pagina beschrijft wat Bird herkent, hoe een inkomend bericht wordt vergeleken en hoe je de tekst wijzigt of trefwoorden toevoegt. De pagina Keywords is de tegenhanger in het dashboard.

Een lijst met trefwoordregels, met de regels van de werkruimte boven de standaardregels die ze vervangen

Wat Bird standaard herkent

Negen woorden registreren een afmelding:

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

Twee woorden draaien die terug: start en unstop.

Het hele bericht moet overeenkomen, niet een deel ervan. Omdat cancel en end trefwoorden zijn, is dat verschil belangrijk: "cancel my 3pm delivery" is een gewoon bericht en geen intrekking van toestemming. Hoofdletters, accenten, herhaalde spaties en leestekens aan het eind worden genegeerd, dus Stop! en STOP komen allebei overeen. Leestekens vóór of in het woord worden niet genegeerd, dus #stop komt niet overeen.

Waar trefwoorden niet worden herkend

Een trefwoord in een groepsbericht wordt overgeslagen, dus een deelnemer kan zich niet afmelden door daar te antwoorden. Respecteer de afmelding die een groepslid uitspreekt in je eigen verzendlogica.

Wanneer de voorkeur wordt vastgelegd

De classificatie loopt tegelijk met het whatsapp.received-event, niet ervoor. Een integratie die dat event volgt, kan daardoor een STOP zien binnenkomen voordat de voorkeur die het vastlegt bestaat. Als je handler op het inkomende bericht reageert door iets te versturen, lees dan de gegevens van de ontvanger opnieuw in in plaats van uit te gaan van de volgorde van de events.

Zien wat er geldt

GET /v1/whatsapp/keyword-rules beschrijft hoe antwoorden op je nummers worden afgehandeld. Zonder filter geeft het één rij per bereik terug: je eigen regel als je die hebt, en anders die van Bird. Een eigen regel zonder waba vervangt de regel van Bird voor dezelfde bewerking en hetzelfde land. Beperk het resultaat met country, waba, operation of scope:

  • scope=system geeft de catalogus van Bird terug, inclusief de standaardregel die een eigen regel van je 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 naar minst specifiek. In die volgorde wordt een inkomend bericht ook met de regels vergeleken. Elke regel bevat effective_keywords: de set van Bird voor die bewerking en dat land, zonder wat je hebt verwijderd en met wat je hebt toegevoegd.

Voor een eigen regel zonder country toont effective_keywords de wereldwijde set van Bird. De regel heeft namelijk geen land, en het land van de afzender is pas bekend als er een bericht binnenkomt. Die regel vergelijkt berichten met de set van Bird voor het land van de afzender, en die set kan groter zijn. Stel een country in op je regel om precies te zien waarop berichten van die afzenders overeenkomen.

country is het land van de afzender, bepaald op basis van diens eigen telefoonnummer en niet het nummer dat diegene een bericht stuurde. Dit is het landsignaal dat WhatsApp meestuurt. Een afzender die wordt geïdentificeerd met een gebruikers-ID op bedrijfsniveau heeft geen land. Een bericht van zo'n afzender slaat de landspecifieke regels daarom over en komt in plaats daarvan overeen met een wereldwijde regel.

Het antwoord wijzigen

De standaardantwoorden van Bird zijn correct maar algemeen. Maak een regel aan om in je eigen naam te antwoorden:

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, wordt herkend zonder dat je iets hoeft te wijzigen.

Wil je niets terugsturen maar de afmelding wel vastleggen, laat dan reply weg wanneer je de regel aanmaakt. Om een bestaande regel stil te zetten, stel je reply in op null in een JSON-body bij de update hieronder; een CLI-vlag kan geen null bevatten.

Een dialoogvenster voor een trefwoordregel met de trefwoorden van Bird, een toegevoegd trefwoord, een verwijderd trefwoord 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);

Als je keywords weglaat, blijven je aanvullingen ongewijzigd. Als je een lege array stuurt, worden ze gewist en geldt weer de set van Bird.

Trefwoorden van Bird verwijderen

In sommige gesprekken zijn cancel of stop gewone woorden, bijvoorbeeld in een botflow waarin cancel betekent dat deze stap wordt geannuleerd. Zet ze in excluded_keywords op je regel:

Codevoorbeeld
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"]}'

Een bericht dat precies uit een van die woorden bestaat, meldt dan niemand af en krijgt geen antwoord voor de mensen die onder de regel vallen. Het bericht komt gewoon bij je binnen, en de eigen regel van Bird handelt het ook niet af. Sluit alle trefwoorden van Bird uit om ze uit te schakelen. Een trefwoord dat Bird later toevoegt, wordt nog wel herkend, tenzij je regel het al uitsluit. Als je trefwoorden verwijdert, moet je zelf de afmeldingen honoreren die ze overbrengen. De eigen afmeldknop van Meta op marketingtemplates blijft werken.

Bij een update vervangt excluded_keywords de verwijderde set, verwijdert een lege array niets en laat weglaten de set ongewijzigd. Een trefwoord kan niet tegelijk toegevoegd en uitgesloten zijn. Elk uitgesloten trefwoord moet een van de trefwoorden van Bird zijn voor de bewerking van de regel. Bij een regel met een country moet het een van de trefwoorden van Bird voor dat land zijn, of een van de wereldwijde trefwoorden van Bird als Bird er voor dat land geen heeft. Bird weigert elk ander woord met een 422, omdat dat woord anders verwijderd zou worden als Bird het later toevoegt.

Bereik van regels en duplicaten

Je beperkt een regel met waba tot één WhatsApp Business Account, met country tot één land van de afzender, tot beide of tot geen van beide. Je hebt één regel per combinatie van bewerking, land en account. Een tweede schrijfactie voor dezelfde combinatie geeft een duplicaatfout.

Bird weigert een regel die stop koppelt aan opt_in, of het woord nu uit de catalogus van Bird komt of uit een andere regel van jou. Zo kan een afmeldwoord nooit toestemming geven.

Een regel verwijderen

Als je je regel verwijdert, gaat dat bereik over naar 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.

Als je je regel voor een land verwijdert, gaat het bereik dus over naar de regel van Bird voor dat land, nog 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.
await bird.whatsapp.keywordRules.delete("wkr_01m2kj8x4te9p0rr7e5w2n1abc");

Als je een regel verwijdert, gelden de formulering en de set trefwoorden van de regel die daarna in die volgorde komt. Is dat een regel van jou die stop uitsluit, dan doet STOP daar ook niets.

Volgende stappen

  • Voorkeuren: de records die een trefwoord aanmaakt, en welke daarvan je kunt terugdraaien.
  • Suppressies: de adressen die je werkruimte rechtstreeks blokkeert.