Verbindungstypen
Das Feld provider hat den Wert qr oder cloud_api. Was jeder Typ kann und wo sich die beiden tatsächlich unterscheiden.
Jede Verbindung meldet einen provider. Er hat einen von zwei Werten:
provider | Was es ist | Wie die Einrichtung läuft |
|---|---|---|
qr | Eine gewöhnliche WhatsApp-Nummer (verkauft als WAPP), die durch das Koppeln eines Geräts verbunden wird. | POST /connections, dann einen QR-Code scannen oder einen Kopplungscode eingeben. Vollständig per Self-Service über die API – kein Meta-Business-Konto nötig. |
cloud_api | Eine WhatsApp-Business-Nummer (verkauft als WABA), die bei Meta über die offizielle Cloud API registriert ist. | Meta Embedded Signup, nicht diese API. |
Beide Typen senden und empfangen über dieselben Endpunkte, mit denselben Request-Bodys und denselben zwei Nachrichten-IDs. Falls Sie angenommen haben, eine QR-Verbindung aus der eigenen Anwendung sei unmöglich: Sie ist möglich.
Wo sie sich tatsächlich unterscheiden
Webhooks. Ereignisse werden nur für qr-Verbindungen ausgelöst.
cloud_api-Verbindungen senden derzeit keine Webhooks – fragen Sie dort
GET /messages und GET /connections/{id} per Polling ab.
Kopplung. POST /connections/{id}/pairing-code gibt es nur bei qr. Eine
cloud_api-Nummer antwortet mit 409 not_supported_for_provider. Das ist eine
dauerhafte Ablehnung, wiederholen Sie die Anfrage also nicht.
Sendelatenz. Ein Versand über qr dauert normalerweise 1–7 s (bei langen
Texten bis zu ~20 s) und kann im Selbstheilungsfall ~2,5 Minuten dauern. Ein
Versand über cloud_api dauert etwa 1 s. Legen Sie Ihr HTTP-Timeout für den
langsameren Fall aus: mindestens 180 s.
Als gelesen markieren. POST /messages/read markiert bei einer
qr-Verbindung den gesamten Chat. Eine cloud_api-Verbindung kann nur eine
bestimmte Nachricht markieren. Eine Anfrage nur mit phone ermittelt daher
automatisch Ihre letzte eingehende Nachricht von dieser Nummer.
Volumen. Eine neu gekoppelte qr-Nummer unterliegt 72 Stunden lang
Warm-up-Limits für das Stundenvolumen. Wird eines überschritten, folgt
429 warmup_limited. Siehe
Lizenzen & Testphase.
Sitzungsstabilität. Eine qr-Verbindung ist an ein Telefon gebunden, das
erreichbar bleiben muss. Sie kann daher abbrechen und eine erneute Kopplung
verlangen – dafür gibt es connection.disconnected / connection.connected
und das Flag needs_reconnect. Eine cloud_api-Verbindung scannt nie etwas und
kennt diesen Fehlerfall nicht.
Unbekannte Provider werden nicht durchgereicht
provider wird auf null abgebildet, statt einen unbekannten Wert
durchzureichen. Sollte je ein neuer Verbindungstyp hinzukommen, wird er hier
gezielt benannt. Eine Verzweigung auf qr / cloud_api ist heute also sicher.
Behandeln Sie null aber als „ein Typ, den dieser Client nicht kennt“, statt
daran abzustürzen.
Workspaces
Ein Schlüssel gehört zu genau einem Workspace. Was das für Multi-Tenant-Anwendungen bedeutet und wie sich ein Bitrix24-Portal von einem eigenständigen Workspace unterscheidet.
Lizenzen & Testphase
Eine kostenlose 7-Tage-Testphase pro Nummer, danach eine monatliche Lizenz pro Nummer. Was ein Slot ist und was passiert, wenn einer abläuft.