Voorkeuren

Een voorkeur is een verklaring over wat iemand wil, vastgelegd bij het adres van die persoon op één kanaal. Op WhatsApp is het adres een telefoonnummer in E.164-formaat. Het is een apart record naast een suppression, en beide worden gecontroleerd vóór een verzending.

Voorkeuren bereiken je werkruimte op drie manieren: WhatsApp meldt er een, een ontvanger typt een sleutelwoord, of je legt er zelf een vast. Wat je met elk ervan kunt doen, hangt af van wie de verklaring heeft afgelegd.

Wat een voorkeur bevat

Een verklaring is ofwel revoked, een opt-out, ofwel granted, toestemming.

Een verklaring heeft ook een dekking, die bepaalt hoeveel verkeer ze tegenhoudt. non_transactional dekt marketing en andere niet-essentiële berichten, terwijl transactionele berichten zoals bonnetjes en verificatiecodes gewoon doorlopen. all dekt elk bericht. Het tabblad Preferences toont deze in de kolom Covers als Non-transactional en All messages.

Een verklaring kan worden beperkt tot één afzender met sender_scope, wat op WhatsApp het zakelijke account identificeert. Zonder die beperking geldt de verklaring kanaalbreed in je werkruimte, inclusief accounts die je later koppelt.

Eén persoon kan meerdere rijen hebben op één kanaal, zoals een kanaalbrede opt-out naast een afzendergebonden opt-out. De meest beperkende verklaring bepaalt of een bericht wordt verzonden.

Voorkeuren die Bird voor je vastlegt

Wanneer Bird een Meta-event ontvangt dat aangeeft dat een ontvanger marketingberichten heeft stopgezet, legt het een voorkeur met oorsprong bij de ontvanger vast voor dat WhatsApp Business Account. De voorkeur dekt niet-transactionele berichten. Er wordt geen suppression voor alle berichten aangemaakt, en de persoon wordt niet afgemeld voor elk account in je werkruimte.

Een ontvanger kan hetzelfde aangeven door STOP te antwoorden. Die voorkeur is gekoppeld aan het zakelijke account waarnaar ze het bericht stuurden, net als de voorgaande. Ze dekt alle berichten, omdat een getypt STOP breder is dan de marketing-opt-out van WhatsApp. Zie sleutelwoordregels voor wat Bird herkent en hoe je het antwoord kunt aanpassen.

Een later hervattingsevent werkt de voorkeur van dat account bij. Suppressions en andere van toepassing zijnde voorkeuren blijven gelden, dus een hervattingsevent alleen bewijst niet dat een verzending is toegestaan.

Voorkeuren die je zelf vastlegt

Open de pagina Suppressions en schakel naar het tabblad Preferences. Als je daar een voorkeur vastlegt met Every business account in the workspace, ontvangt het adres geen WhatsApp-berichten meer van welk account dan ook, inclusief accounts die je later koppelt.

Een lijst van abonnees die zich hebben aan- of afgemeld, met de dekking van elke verklaring

Het dialoogvenster Record opt-out op dat tabblad legt dekking voor alle berichten vast.

Een dialoogvenster voor het vastleggen van een opt-out, met het werkruimtebrede bereik geselecteerd

Om er een vast te leggen die alleen marketing stopt, gebruik je de werkruimtebrede pagina Contacts > Preferences, waarvan het dialoogvenster Marketing messages en All messages aanbiedt.

Voorkeuren uitlezen vanuit code

GET /v1/preferences geeft de vastgelegde voorkeuren van de werkruimte terug, meest recent aangemaakt eerst. Geef channel=whatsapp mee om te beperken tot dit kanaal, en handle erbij om alles op te zoeken wat voor één nummer is vastgelegd voordat je ze een bericht stuurt:

for await (const preference of bird.preferences.list({
  channel: "whatsapp",
  handle: "+15550001234",
})) {
  console.log(preference.status, preference.coverage, preference.sender_scope);
}

for preference in client.preferences.list(channel="whatsapp", handle="+15550001234"):
    print(preference.status, preference.coverage, preference.sender_scope)

for pref, err := range client.Preferences.List(context.Background(), bird.PreferencesListParams{
	Channel: bird.PreferenceChannelWhatsapp,
	Handle:  "+15550001234",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(*pref.Status, *pref.Coverage)
}

foreach ($bird->preferences->list(['channel' => 'whatsapp', 'handle' => '+15550001234']) as $preference) {
    echo $preference->getStatus(), ' ', $preference->getCoverage(), PHP_EOL;
}

bird preferences list --channel whatsapp --handle +15550001234

curl "https://us1.platform.bird.com/v1/preferences?channel=whatsapp&handle=%2B15550001234" \
  -H "Authorization: Bearer $BIRD_API_KEY"

handle vereist channel, omdat hetzelfde adres op meer dan één kanaal kan bestaan.

Een voorkeur vastleggen vanuit code

POST /v1/preferences legt één verklaring vast. Het schrijven is een upsert op basis van kanaal, adres en afzenderbereik, dus een nieuwe verklaring vervangt de huidige op die sleutel:

const result = await bird.preferences.create({
  channel: "whatsapp",
  handle: "+15550001234",
  status: "revoked",
  coverage: "non_transactional",
});
console.log(result.applied, result.preference?.id);

result = client.preferences.create(
    channel="whatsapp",
    handle="+15550001234",
    status="revoked",
    coverage="non_transactional",
)
print(result.applied, result.preference.id)

result, err := client.Preferences.Create(context.Background(), bird.PreferencesCreateParams{
	Channel:  bird.PreferenceChannelWhatsapp,
	Handle:   "+15550001234",
	Status:   bird.PreferenceStatusRevoked,
	Coverage: bird.PreferenceCoverageNonTransactional,
})
if err != nil {
	log.Fatal(err)
}
// A newer statement already on file answers Applied false instead of an
// error, with the surviving statement in Preference.
if result.Applied != nil && *result.Applied {
	fmt.Println("opt-out recorded")
}

$result = $bird->preferences->create(
    channel: 'whatsapp',
    handle: '+15550001234',
    status: 'revoked',
    coverage: 'non_transactional',
);
echo var_export($result->getApplied(), true);

bird preferences create \
  --channel whatsapp \
  --handle +15550001234 \
  --status revoked \
  --coverage non_transactional

curl -X POST https://us1.platform.bird.com/v1/preferences \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"whatsapp","handle":"+15550001234","status":"revoked","coverage":"non_transactional"}'

Verklaringen worden gerangschikt op het moment waarop ze zijn afgelegd, niet op het moment van aankomst. De API weigert een verklaring die ouder is dan de huidige op die sleutel en retourneert applied: false met de verklaring die bewaard bleef. De weigering blijft in de geschiedenis van de sleutel staan.

Een 201 betekent dat de sleutel geen record had en deze verklaring er een heeft aangemaakt. Een 200 retourneert het bewaard gebleven record van de sleutel, ongeacht of deze verklaring het heeft vervangen, herhaald of geweigerd is.

Wat je kunt terugdraaien

Een voorkeur die je zelf hebt vastgelegd, kun je verwijderen via het tabblad Preferences of met DELETE /v1/preferences/{preference_id} zodra de ontvanger je vraagt de verzending te hervatten.

Een verklaring die de persoon zelf heeft afgelegd, kan alleen door diegene worden teruggedraaid. Een uitschrijving of een stopsleutelwoord eindigt wanneer ze opnieuw toestemming geven, en een delete retourneert 422. Om het berichtenverkeer te hervatten met hun toestemming, leg je een granted-verklaring vast met consented_at, het moment waarop ze toestemming gaven. De toekenning geldt wanneer dat moment later is dan de opt-out die ze terugdraait, zodat de verandering van mening wordt vastgelegd in plaats van de oorspronkelijke verklaring te wissen.

Een delete wordt gerangschikt als elke andere verklaring, op basis van het moment van ontvangst. Als het record een verklaring bevat die na dat moment is afgelegd, wordt de delete geweigerd en geretourneerd met applied: false samen met het bewaard gebleven record.

Wanneer een afleveringsfout eerder binnenkomt

Een afleveringsfout van de provider kan een stop melden voordat Bird een bijbehorend event heeft vastgelegd. Respecteer de keuze van de ontvanger en onderzoek de voorkeurs- en eventgeschiedenis in plaats van een ontbrekend lokaal record te behandelen als toestemming om te verzenden.

Volgende stappen

Suppressions: de adressen die je werkruimte rechtstreeks blokkeert.
Sleutelwoordregels: de woorden die een voorkeur vastleggen op je nummers.
WhatsApp-events: de whatsapp.rejected-payload die een geblokkeerde verzending oplevert.

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 channel Begrijp het conceptWhat is the 24-hour customer service window on WhatsApp?Gebruik de toolWhatsApp message builder Ontdek de mogelijkheidWhatsApp

Probeer de oefening en ontvang een implementatieoverzicht