Erste Schritte mit der WhatsApp Public API

Mit der WhatsApp Public API von Aircall können Entwickler und externe Tools (HubSpot, Salesforce und benutzerdefinierte Skripte) WhatsApp-Nachrichten programmgesteuert im Namen Ihres Unternehmens senden, ohne dass ein Agent sie manuell aus Aircall Workspace sendet. Dieser Artikel erklärt, wer die API nutzen kann, wie eine Leitung registriert wird und was jeder Endpunkt macht.

Wer kann die WhatsApp Public API nutzen?

Alle vier folgenden Bedingungen müssen erfüllt sein, bevor die API für Ihr Unternehmen funktioniert:

• Aircall Professional-Tarif: Essentials-Konten sind nicht berechtigt und geben einen 403-Fehler zurück.
• WhatsApp-Add-on: mindestens eine aktive WhatsApp-Add-on-Lizenz im Konto.
• Funktionsverfügbarkeit: Sie wird für berechtigte Kunden automatisch aktiviert und erfordert keine Aktion, es sei denn, sie wurde deaktiviert. Wenn Sie vermuten, dass sie deaktiviert wurde, kontaktieren Sie den Aircall Support.
• Leitungsregistrierung: Die WhatsApp-Leitung muss vor dem Senden über den Konfigurationsendpunkt für die Nutzung mit der Public API registriert werden.

ACHTUNG:
Alle Bedingungen müssen erfüllt sein. Wenn auch nur eine fehlt, funktioniert die API für dieses Unternehmen nicht.

Die zwei Sendemodi

Wenn Sie eine WhatsApp-Nachricht über die API senden, wählen Sie zwischen zwei Modi.

• Proxy-Versand: Die Nachricht wird im Namen des Entwicklers gesendet und erscheint nicht im Posteingang des Agents. Zustellungsaktualisierungen und eingehende Antworten werden an die registrierte callbackUrl gesendet.
• Nativer Versand: Die Nachricht wird gesendet und erscheint in der Workspace-Unterhaltung des Agents. Der Agent kann die Unterhaltung in Aircall sehen und fortsetzen.

HINWEIS:
Die beiden Sendemodi schließen sich gegenseitig aus. Proxy-Versand erfordert, dass die Leitung über den Konfigurationsendpunkt für die Nutzung mit der Public API registriert ist. Nativer Versand erfordert, dass sie nicht registriert ist.

Die vier API-Endpunkte

Eine Leitung für die Nutzung mit der Public API registrieren

POST /v1/numbers/{id}/messages/configuration

Registrieren Sie eine WhatsApp-Leitung und geben Sie eine callbackUrl an: die URL, an die Aircall Zustellungsaktualisierungen und eingehende Antworten sendet. Dieser Schritt muss abgeschlossen sein, bevor Nachrichten gesendet werden können.

ACHTUNG:
Wenn die API nicht funktioniert, prüfen Sie zuerst, ob die Leitung über diesen Endpunkt registriert wurde. Ohne Registrierung geben alle Sendeversuche einen Fehler zurück.

Leitungsstatus prüfen

GET /v1/numbers/{id}/whatsapp_status

Gibt den aktuellen Status einer WhatsApp-Leitung zurück. Rufen Sie diesen Endpunkt vor dem Senden auf, um zu bestätigen, dass sich die Leitung in einem fehlerfreien Zustand befindet. Die Antwort umfasst:

• Status: ob die Leitung ONLINE, OFFLINE oder NOT_REGISTERED ist
• canSendMessage: ob die Leitung aktuell senden kann (AVAILABLE, LIMITED oder BLOCKED)
• qualityRating: Metas Signal zur Interaktion der Empfänger (GREEN, YELLOW oder RED)
• messagingLimitTier: die maximale Anzahl geschäftlich initiierter Unterhaltungen, die die Leitung pro 24 Stunden starten kann (TIER_250, TIER_1K, TIER_10K oder TIER_100K)

Eine Nachricht senden

POST /v1/messages/whatsapp/send

POST /v1/messages/send/whatsapp/native

Sendet eine WhatsApp-Nachricht programmgesteuert. Zwei Nachrichtentypen werden unterstützt:

• Genehmigte Vorlagen: können jederzeit gesendet werden, innerhalb oder außerhalb des 24-Stunden-Unterhaltungsfensters
• Freitext: kann nur innerhalb eines offenen 24-Stunden-Unterhaltungsfensters gesendet werden

Weitere Details dazu, wann welcher Typ gilt, finden Sie unten unter „Das 24-Stunden-Unterhaltungsfenster“.

Verfügbare Vorlagen auflisten

GET /v1/numbers/{id}/templates

Gibt alle WhatsApp-Nachrichtenvorlagen für eine Leitung zurück, einschließlich ihres Genehmigungsstatus (APPROVED, PENDING, REJECTED, PAUSED oder DISABLED) und der Variablenstruktur für jede Vorlage. Verwenden Sie diesen Endpunkt, um vor dem Senden zu bestätigen, welche Vorlagen verfügbar sind.

Einrichtung der WhatsApp Public API

Schritte:

1. Bestätigen Sie, dass Ihr Konto den Pro-Tarif nutzt und mindestens eine aktive WhatsApp-Add-on-Lizenz hat.
2. Rufen Sie POST /v1/numbers/{id}/messages/configuration mit Ihrer WhatsApp-Leitungs-ID und Ihrer callbackUrl auf, um die Leitung zu registrieren.
3. Rufen Sie GET /v1/numbers/{id}/whatsapp_status auf, um zu bestätigen, dass die Leitung ONLINE ist und canSendMessage AVAILABLE anzeigt.
4. Rufen Sie GET /v1/numbers/{id}/templates auf, um Ihre genehmigten Vorlagen abzurufen.
5. Senden Sie Ihre erste Nachricht mit POST /v1/messages/whatsapp/send.

TIPP:
Prüfen Sie vor dem Senden immer den Leitungsstatus, insbesondere in automatisierten Workflows. Der Status einer Leitung kann sich abhängig von qualityRating und den Regeln von Meta ändern. Eine Statusprüfung vor dem Senden in Ihrer Integration verhindert fehlgeschlagene Sendungen.

Das 24-Stunden-Unterhaltungsfenster

Metas Regel zum Unterhaltungsfenster steuert, wann Freitextnachrichten gesendet werden können:

• Wenn ein Kunde Ihrer Nummer schreibt oder auf eine Ihrer Nachrichten antwortet, wird ein 24-Stunden-Fenster geöffnet.
• Innerhalb dieses Fensters können Sie Freitextnachrichten senden.
• Sobald das Fenster geschlossen ist (keine Antwort des Kunden innerhalb von 24 Stunden), können nur genehmigte Vorlagen gesendet werden, um den Kontakt erneut zu initiieren.

HINWEIS:
Das Senden von Freitext außerhalb eines offenen Fensters gibt eine 200-Antwort zurück, aber Ihr registrierter Webhook erhält einen Callback mit einem 63016-Fehler. Verwenden Sie eine genehmigte Vorlage, um die Unterhaltung erneut zu öffnen. Aircall kann das Fenster nicht außer Kraft setzen oder verlängern.

API-Referenz

Die vollständigen Anfrage- und Antwortschemata, Authentifizierungsdetails und Codebeispiele finden Sie in der Entwicklerdokumentation von Aircall.