So ermitteln Sie mit der Twilio Lookup API, ob eine Telefonnummer noch derselben Person gehört

So ermitteln Sie mit der Twilio Lookup API, ob eine Telefonnummer noch derselben Person gehört

Um die Vorgaben des Telephone Consumer Protection Act (TCPA) einzuhalten, benötigen Sie die Einwilligung der Personen, die Sie über Ihre Anwendung kontaktieren möchten. Eine häufige Ursache für TCPA-Verstöße ist die Neuzuweisung einer Telefonnummer, die zuvor einer Person gehörte, die einer Kontaktaufnahme zugestimmt hatte. Vielleicht haben Sie ursprünglich die Einwilligung zur Kontaktaufnahme mit dem damaligen Inhaber der Telefonnummer erhalten. Wird die Nummer später einer anderen Person zugewiesen, gilt diese Einwilligung für den neuen Inhaber aber nicht mehr.

Mit der Twilio Lookup API können Sie zuverlässig feststellen, ob eine Telefonnummer neu zugewiesen wurde. So verbessern Sie Ihre Kontaktraten, steigern die Effizienz Ihrer Kampagnen und vermeiden Strafzahlungen wegen Compliance-Verstößen. Diese Funktion ist besonders für Marketingbenachrichtigungen nützlich.

So richten Sie die Twilio Lookup API für neu zugewiesene Rufnummern ein und verwenden sie

Für die Verwendung der Lookup API benötigen Sie:

1. ein Twilio-Konto – registrieren Sie sich noch heute
2. Twilio-Testzugangsdaten – Sie finden sie auf der Seite „Auth Tokens“ in der Console)
3. Für den produktiven Einsatz benötigen Sie zusätzlich eine Genehmigung für das Datenpaket „Reassigned Number“. Die Genehmigung dauert in der Regel zwei bis vier Werktage. Hinweis: Mit Testzugangsdaten können Sie die API in der Entwicklungsumgebung sofort verwenden.

In diesem Tutorial rufen Sie die Lookup API mit Testzugangsdaten auf. So erhalten Sie eine festgelegte Antwort für neu zugewiesene Rufnummern.

Neben der Telefonnummer benötigt die API-Anfrage zwei Parameter:

1. Fields: reassigned_number. Die Lookup API bietet verschiedene Datenpakete, die Sie über den Parameter Fields angeben. Weitere Datenpakete anzeigen.
2. LastVerifiedDate. Im Format YYYYMMDD geben Sie hier das Datum an, an dem Sie die Einwilligung des Endnutzers zur Kontaktaufnahme eingeholt oder ihn zuletzt kontaktiert haben oder an dem der Endnutzer seine Telefonnummer in Ihrer Anwendung zuletzt aktualisiert hat.

Sobald Ihnen die Testzugangsdaten vorliegen, ersetzen Sie damit die Zugangsdaten in der folgenden Anfrage. In der Dokumentation erfahren Sie, wie Sie dieselbe Anfrage mit Node.js, Python und weiteren Programmiersprachen stellen.

Aus der API-Antwort geht hervor, dass die Rufnummer neu zugewiesen wurde. In der Antwort finden Sie außerdem weitere Schlüssel wie sim_swap oder line_type_intelligence, deren Wert null sein kann. Das liegt daran, dass Sie mit dem Parameter Fields mehrere Datenpakete gleichzeitig anfordern können. Lookup liefert standardmäßig auch Informationen zur Formatierung und Validierung.

Beachten Sie, dass das Feld is_number_reassigned keinen booleschen Wert enthält, sondern einen von drei möglichen Werten:

1. yes. Die Rufnummer wurde seit dem zuletzt verifizierten Datum neu zugewiesen. Kontaktieren Sie den Nutzer daher auf anderem Weg und bitten Sie ihn erneut um seine aktuelle Telefonnummer und die Einwilligung zur Kontaktaufnahme.
2. no. Die Telefonnummer gehört weiterhin demselben Endnutzer. Zusammen mit einem Einwilligungsnachweis kann diese Antwort den Safe-Harbor-Schutz nach dem TCPA bieten.
3. no_data_available. Dieser Wert bedeutet in der Regel, dass LastVerifiedDate vor Januar 2021 liegt. In diesem Fall sollten Sie die Einwilligung zur Kontaktaufnahme erneut einholen.

Testen Sie weitere mögliche Antworten mit anderen Magic Numbers für Lookup.

So funktionieren die FCC-Datenbank und der „Safe Harbor“

Twilio nutzt die offizielle Datenbank der Federal Communications Commission (FCC). Sie wird jeweils am 16. eines Monats aktualisiert. Wenn Sie den Neuzuweisungsstatus von Rufnummern häufiger als einmal im Monat prüfen müssen, empfehlen wir, Ihre Datenbank jeweils am 17. des Monats zu aktualisieren. Die an diesem Tag abgerufenen Daten bleiben bis zur nächsten Aktualisierung der Datenbank am 16. des Folgemonats gültig. Sollte es Probleme mit der Datenbank geben, können Anrufer nach Angaben der FCC bei entsprechender Dokumentation möglicherweise vor einer Haftung geschützt sein.

Die 45-Tage-Sperrfrist

Um Verzögerungen bei der Meldung auszugleichen, hat die FCC eine verbindliche Sperrfrist von 45 Tagen eingeführt. Dienstanbieter dürfen eine deaktivierte Rufnummer frühestens 45 Tage nach der Deaktivierung einem neuen Nutzer zuweisen.

Da Anbieter Deaktivierungen bis zum 15. jedes Monats melden müssen, gibt Ihnen diese 45-Tage-Frist als Anrufer einen zusätzlichen Sicherheitspuffer. Beispiel:

• Tag 1: Ein Kunde lässt seine Rufnummer deaktivieren.

• Tag 15: Der Anbieter meldet die Deaktivierung an die FCC.

• Tag 16: Die Datenbank wird aktualisiert.

• Ab Tag 45: Erst jetzt darf die Rufnummer rechtmäßig einer anderen Person zugewiesen werden. Für diese neue Person gilt die ursprüngliche Einwilligung nicht.

Safe Harbor

Eine Antwort mit dem Wert "no" von der Lookup Reassigned Number API stellt die Einhaltung des TCPA sicher und dient als Nachweis für die unten genannten Punkte 2 und 3 des von der FCC definierten Safe Harbor:

Um nach dem TCPA vor Haftung geschützt zu sein, muss ein Anrufer Folgendes nachweisen: (1) Er hat die Einwilligung des vorgesehenen Empfängers eingeholt. (2) Er oder ein ordnungsgemäß bevollmächtigter Vertreter hat vor dem Anruf in der Datenbank geprüft, dass die Rufnummer nach Erteilung der Einwilligung weder dauerhaft deaktiviert noch neu zugewiesen wurde. (3) Die Datenbank hat fälschlicherweise die Antwort "no" zurückgegeben.

Die FCC weist darauf hin, dass keine Datenbank in Echtzeit aktualisiert wird. Der Safe Harbor bietet Ihnen rechtlichen Schutz, wenn Sie die offizielle Quelle mit der gebotenen Sorgfalt prüfen. Sie sind jedoch weiterhin dafür verantwortlich, die Einwilligung des vorgesehenen Empfängers für den Anruf nachzuweisen.

Häufige Fehlercodes beheben

Wenn bei der API ein Fehler auftritt, finden Sie den Fehlercode unter dem Antwortschlüssel reassigned_number. Trotz des Fehlers lautet der Statuscode der API-Antwort 200. Das liegt daran, dass Sie mit einer Anfrage mehrere Lookup-Datenpakete abrufen können und der Aufruf für einige davon erfolgreich sein kann.

Dabei können vier häufige Fehler auftreten:

• 60606: Das Datenpaket ist nicht aktiviert. Beantragen Sie den Zugriff über dieses Formular. Bis zur Freischaltung können Sie mit Testzugangsdaten und Magic Numbers testen.
• 60607: Die Anfrage betrifft eine Telefonnummer außerhalb der USA. Das Datenpaket „Reassigned Number“ unterstützt nur Rufnummern in den USA.
• 60617: LastVerifiedDate fehlt.
• 60618: LastVerifiedDate ist nicht korrekt formatiert. Das korrekte Format lautet YYYYMMDD. Entfernen Sie alle Bindestriche und Leerzeichen.

Erkennung neu zugewiesener Rufnummern im Produktivbetrieb einsetzen

Bei Marketingnachrichten ist die Einhaltung der geltenden Vorschriften unerlässlich. Die Erkennung neu zugewiesener Rufnummern hilft Ihnen, Strafzahlungen zu vermeiden. Twilio führt keine eigene Sperrliste für Werbeanrufe. Wir empfehlen daher, Lookup Reassigned Numbers zusammen mit der National Do Not Call List zu verwenden, um für Ihre Nutzerbasis zu ermitteln, ob eine Einwilligung zur Kontaktaufnahme vorliegt. Bevor Sie Ihre Anwendung im Produktivbetrieb verwenden, benötigen Sie die erforderliche Genehmigung des Netzbetreibers. Nutzen Sie für Ihre Anfragen anschließend die produktiven API-Schlüssel anstelle der Testzugangsdaten.

Wenn die Erkennung neu zugewiesener Rufnummern eingerichtet ist, können Sie über Code Exchange weitere Lookup-Datenpakete ausprobieren. Mit Line Type Intelligence können Sie beispielsweise VoIP-Rufnummern erkennen oder mit SIM Swap prüfen, ob bei einer Telefonnummer ein SIM-Tausch stattgefunden hat, bevor Sie eine SMS-2FA-Anfrage senden. Anschließend können Sie die Verify API integrieren, um zu prüfen, ob der Nutzer Zugriff auf die Telefonnummer hat, und die Nutzerüberprüfung abzuschließen. Ich bin gespannt, welche Projekte Sie entwickeln und wie Sie sie absichern!