Sign inGet started

Unterdrückungen

Eine Unterdrückung ist eine Adresse, die Ihr Workspace nicht kontaktiert, gespeichert mit einem Geltungsbereich. Bird blockiert einen Versand an eine unterdrückte Adresse, bevor er WhatsApp erreicht.
Öffnen Sie die Seite Suppressions, um mit der Liste zu arbeiten, oder nutzen Sie die API unten. Vom Empfänger gesetzte Einträge befinden sich auf dem Tab Preferences derselben Seite und folgen anderen Regeln.
Eine Liste mit vier gesperrten Nummern, jeweils auf alle Business-Accounts oder auf einen einzelnen beschränkt

Einen Business-Account unterdrücken

Erstellen Sie im Tab Suppressions eine Unterdrückung für eine Telefonnummer und wählen Sie den Business-Account, für den sie gilt. Bird blockiert Nachrichten von diesem Account, und Ihre anderen Accounts können die Nummer weiterhin kontaktieren. Die Spalte Business account der Liste zeigt den Account, auf den eine Unterdrückung begrenzt ist, oder All accounts für eine, die Ihren gesamten Workspace abdeckt.
POST /v1/whatsapp/suppressions speichert dasselbe per Code. waba ist der Account, auf den die Unterdrückung begrenzt wird; lassen Sie ihn weg, um die Adresse für Ihren gesamten Workspace zu blockieren, einschließlich Accounts, die Sie später verbinden:
// Omit waba to block the address for the whole workspace, whichever account
// sends. With it, your other accounts keep reaching them, and the same
// address for two accounts is two records.
const suppression = await bird.whatsapp.suppressions.add({
  address: "+15550001234",
  waba: "102290129340398",
});
console.log(suppression.id, suppression.applies_to);
Ein Dialog zum Sperren einer Nummer, mit dem Geltungsbereich auf einen einzelnen Business-Account gesetzt

Ein Geltungsbereich, ein Eintrag

Eine Unterdrückung hat genau einen Geltungsbereich. Dieselbe Adresse, die für zwei Accounts blockiert ist, ergibt daher zwei Einträge statt einem. Um den gesamten Workspace abzudecken, führen Sie einen Aufruf ohne waba aus.
Wird eine Adresse hinzugefügt, die für diesen Geltungsbereich bereits unterdrückt ist, gibt die Antwort 200 mit dem bestehenden Eintrag zurück, statt einen zweiten anzulegen. Ein neuer Eintrag gibt 201 zurück.
Eine Unterdrückung ist auf die von Ihnen erfasste Adresse bezogen. Ein Empfänger, der über eine Telefonnummer erreicht wird, und derselbe Empfänger, der über eine Business-bezogene User-ID erreicht wird, sind zwei Schlüssel – die Unterdrückung des einen unterdrückt also nicht den anderen. Erfassen Sie beide, wenn Sie dieselbe Person auf beiden Wegen adressieren.

Ihre Unterdrückungsliste lesen

GET /v1/whatsapp/suppressions gibt die aktiven Unterdrückungen zurück, die neuesten zuerst, als Cursor-Seite. address filtert nach Präfix und ignoriert Groß-/Kleinschreibung: ein Teilwert trifft jede Adresse darunter, ein vollständiger Wert nur diese eine Adresse. reason schränkt auf eine Kategorie ein, z. B. manual für die von Ihnen hinzugefügten:
// address is a prefix, so a partial value matches every address under it.
const suppressions = await bird.whatsapp.suppressions.list({ address: "+1555" });
for (const suppression of suppressions.data ?? []) {
  console.log(suppression.address, suppression.waba ?? "every account");
}
Die Liste enthält nur aktive Einträge; beendete Einträge fehlen. Eine fehlende Adresse beweist nicht, dass der Workspace sie nie unterdrückt hat – der Eintrag kann beendet worden sein. Lesen Sie ihn per ID, um sicherzugehen.

Einen einzelnen Eintrag lesen

GET /v1/whatsapp/suppressions/{suppression_id} löst sowohl einen beendeten als auch einen aktiven Eintrag auf und zeigt, wann er beendet wurde und wodurch:
// Resolves a record that has already ended, which the list leaves out.
const suppression = await bird.whatsapp.suppressions.get("was_01krdgeqcxet5s7t44vh8rt9mg");
console.log(suppression.reason, suppression.ended_at ?? "still in force");

Eine Unterdrückung beenden

Die Aktion Delete in einer Unterdrückungszeile beendet die Unterdrückung, statt sie zu entfernen. Die Blockierung endet. Der Eintrag bleibt lesbar und zeigt, wann und von wem er beendet wurde. DELETE /v1/whatsapp/suppressions/{suppression_id} bewirkt dasselbe und gibt 204 zurück:
// Only a manual suppression can be ended; a recipient's own opt-out is
// theirs to reverse. The record is kept and still reads back by id.
await bird.whatsapp.suppressions.remove("was_01krdgeqcxet5s7t44vh8rt9mg");
Eine von Ihnen selbst hinzugefügte Unterdrückung hat den Grund manual und kann beendet werden. Ein Opt-out des Empfängers kann nur von ihm selbst rückgängig gemacht werden; der Versuch gibt 422 zurück. Ein erneuter Aufruf für eine bereits beendete Unterdrückung ist erfolgreich und ändert nichts, und eine ID, die der Workspace nicht enthält, gibt 404 zurück.
Das Beenden einer Unterdrückung erfordert deren ID – schlagen Sie sie daher zuerst über die Liste nach.

Neue Unterdrückungen beobachten

whatsapp_suppression.created wird ausgelöst, wenn eine Unterdrückung erfasst wird, sodass Ihr eigenes System neue Blockierungen ohne Polling erkennen kann. Der Payload enthält:
  • suppression_id, der Bezeichner des Eintrags.
  • address, die unterdrückte Nummer im E.164-Format.
  • waba, der Account, auf den die Blockierung begrenzt ist, oder null, wenn sie den gesamten Workspace abdeckt.
  • reason und workspace_id.
Beim Beenden einer Unterdrückung wird kein Event ausgelöst. Lesen Sie die Liste daher erneut, bevor Sie einer gespeicherten Kopie vertrauen. Siehe WhatsApp-Events für den vollständigen Payload.

Nächste Schritte

  • Preferences: die vom Empfänger gesetzten Einträge und welche davon Sie rückgängig machen können.
  • WhatsApp-Events: der whatsapp.rejected-Payload, den ein blockierter Versand erzeugt.
  • WhatsApp-Nachrichten senden: die Versand-API und ihr asynchrones Zustellmodell.