Kontakte

/v1/contacts

Verwalte WhatsApp-Benutzer*innen in deiner Datenbank mit dem contacts-Node, indem du sie validierst, bevor Nachrichten gesendet werden. Bestätige außerdem die Identität von Benutzer*innen mit Identitäts-Hashes.

Der Node contacts ermöglicht Folgendes:

• Bestätigung, dass eine Telefonnummer in deiner Datenbank zu einem gültigen WhatsApp-Konto gehört. Du musst sicherstellen, dass der statusvalid lautet, bevor du einem*einer Benutzer*in eine Nachricht senden kannst.
• Erhalt der WhatsApp-ID für eine Telefonnummer. WhatsApp-IDs werden benötigt, um Nachrichten und Benachrichtigungen für Benutzer*innen zu senden.

Bevor du beginnst

Du musst deinen Kund*innen die Möglichkeit bieten, WhatsApp-Kommunikationen mit deinem Unternehmen beizutreten. Dieser Beitrittsvorgang wird von deinem Unternehmen verwaltet. Verwende nach dem Beitritt eines*einer Kund*in den contacts-Node, um die registrierte Nummer zu verifizieren. Weitere Informationen dazu findest du unter Informationen zur Einholung der Zustimmung zu WhatsApp.

Einschränkungen

• Verwende diesen Endpunkt zur Bestätigung, dass eine Telefonnummer in der Datenbank eines Unternehmens zu einem gültigen WhatsApp-Konto gehört.
• Die Anzahl der Anrufe darf nicht höher sein als die Anzahl der Nachrichten, die von der Telefonnummer gesendet werden.

Durchsetzung

Wenn ein Unternehmen den Endpunkt falsch verwendet, werden die folgenden Maßnahmen ergriffen:

• Alle im Business Manager aufgeführten Administrator*innen erhalten bei Verdacht auf missbräuchliche Nutzung eine erste Warnung per E-Mail.
• Ein Unternehmen hat nach Erhalt der Warnung sieben Tage Zeit, sein Verhalten anzupassen
• Wenn die Aufrufe nach sieben Tagen noch nicht angepasst wurden, wird die Rufnummer dauerhaft deaktiviert.

Empfehlungen

Am besten überprüfst du die Kontakte vor jeder gesendeten Nachricht. Du musst jedoch keine Kontakte überprüfen, um auf eine eingehende Kundennachricht zu antworten. Du kannst mit der wa_id sofort antworten. Es fallen keine zusätzlichen Kosten an, da die Ergebnisse zwischengespeichert werden.

Erstellen

Sende vor dem Senden von Nachrichten an Benutzer*innen, die dies so eingestellt haben, eine POST-Anfrage an /v1/contacts, um eine Anfrage zur Überprüfung eines*einer WhatsApp Account-Benutzer*in zu erstellen. Schließe in den Aufruf eine Liste von Telefonnummern ein, die du überprüfen möchtest.

Beispiel

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

Du erhältst eine Antwort mit dem aktuellen status der angefragten Nummern und deren WhatsApp-IDs (wa_id):

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

Speichere die WhatsApp-IDs für die Nummern, die einen status von valid zurückgesendet haben. Gültige Nutzer sind diejenigen mit einem WhatsApp-Konto. Verwende die WhatsApp-IDs zum Senden von Nachrichten und Benachrichtigungen.

Wiederhole diese Schritte regelmäßig, um die Liste deiner gültigen Benutzer*innen zu verwalten. Die Ergebnisse werden in der Datenbank des WhatsApp Business On-Premises API-Clients 7 Tage lang zwischengespeichert.

Parameter

Die folgenden Parameter werden für POST-Aufrufe an /v1/contacts unterstützt:

Edges

Die folgenden Edges sind mit diesem Node verbunden:

Blockierung

Es gibt zwei Optionen für die blocking-Parameter: no_wait und wait. Wenn der blocking-Parameter in einem Anruf nicht angegeben ist, lautet der Standardwert no_wait.

Der blocking-Parameter bestimmt, ob die Anfrage auf den Abschluss der Verarbeitung warten sollte (synchron) oder nicht (asynchron).

Formate von Telefonnummern

Die Telefonnummern in der contacts-Anfrage können jedes beliebige wählbare Format aufweisen.

Nachfolgend findest du einige Beispiele, die diesen Vorgang beschreiben. Dabei wird davon ausgegangen, dass der WhatsApp Business On-Premises API-Client mit einer indischen Telefonnummer (d. h. mit der Ländervorwahl +91) registriert ist:

Zurückgegebene Felder

Der contacts-Antwort-Payload enthält dasselbe Array an Telefonnummern mit den Eigenschaften input, status und wa_id, die bei der Anfrage gesendet wurden:

Neben dem processing-Status solltest du den HTTP-Status 200 OK sehen.

Wenn eine Vorlagennachricht an eine Telefonnummer ohne WhatsApp-Konto gesendet wird, erhältst du die Fehlermeldung „Benutzer ist ungültig“ mit dem Fehlercode 1013.

Informationen zu anderen Fehlern in der Antwort findest du unter Fehler- und Statusmeldungen.

Blockieren von Kontakten

Das Blockieren kann als Verteidigungsfunktion gesehen werden, um böswillige Nutzer*innen daran zu hindern, schadhafte Aktionen auszuführen. Um einen Kontakt blockieren zu können, muss dieser dir innerhalb der letzten 24 Stunden eine Nachricht gesendet haben.

Beispiel

Sende einen API-Aufruf an /v1/contacts/{phone_number}/block mit einen Grund zur Blockierung eines anderen WhatsApp-Kontos.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

Eine erfolgreiche Antwort weist den HTTP-Status 200 und keine „Fehlerobjekte“ auf.

Eine nicht erfolgreiche Antwort sieht zum Beispiel wie folgt aus:

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Parameter

Die folgenden Parameter werden für POST-Aufrufe an /v1/contacts/{phone_number}/block unterstützt:

Blockierung von Kontakten aufheben

Führe diesen Aufruf aus, um die Blockierung eines Kontakts aufzuheben

Beispiel

Sende einen API-Aufruf an /v1/contacts/{phone_number}/unblock.

POST /v1/contacts/+16315551000/unblock

Eine erfolgreiche Antwort weist den HTTP-Status 200 und keine „Fehlerobjekte“ auf.

Eine nicht erfolgreiche Antwort sieht zum Beispiel wie folgt aus:

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

Parameter

Die folgenden Parameter werden für POST-Aufrufe an /v1/contacts/{phone_number}/unblock unterstützt:

Blockierungsliste

So rufst du eine Liste deiner blockierten Kontakte ab.

Beispiel

Sende einen API-Aufruf an /v1/contacts/blocklist, um eine Liste deiner blockierten Kontakte zu erhalten.

GET /v1/contacts/blocklist?limit=10&offset=0

Du erhältst eine Antwort mit einer Seite deiner Blockierliste und Informationen zur Paginierung.

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

Parameter

Die folgenden Parameter werden für GET-Aufrufe an /v1/contacts/blocklist unterstützt:

Melden

Durch das Melden werden wichtige Signale für das Einrichten präventiver Maßnahmen gegen böswilliger Nutzer*innen gesendet. Damit du einen Kontakt melden kannst, muss dieser dir innerhalb der letzten 24 Stunden eine Nachricht gesendet haben.

Beispiel

Sende einen API-Aufruf an /v1/contacts/{phone_number}/report und gib den Grund an, weshalb das andere WhatsApp-Konto blockiert werden soll.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

Eine erfolgreiche Antwort weist den HTTP-Status 200 und keine „Fehlerobjekte“ auf.

Eine nicht erfolgreiche Antwort sieht zum Beispiel wie folgt aus:

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

Parameter

Die folgenden Parameter werden für POST-Aufrufe an /v1/contacts/{phone_number}/report unterstützt: