Scopes
Vier Scopes, bei jeder Anfrage live aufgelöst. Welche Endpunkte welchen Scope benötigen und warum „Als gelesen markieren“ ein Senden ist.
Scopes gelten pro Zugangsdaten – pro API key oder pro OAuth-Grant. Es gibt vier.
| Scope | Berechtigt zu |
|---|---|
whatsapp.read | GET /connections, GET /connections/{id}, GET /account, GET /messages |
whatsapp.send | POST /messages, POST /messages/read |
whatsapp.events | GET /webhook, PUT /webhook, POST /webhook/rotate und überhaupt dem Empfang von Zustellungen |
whatsapp.manage | POST /connections, POST /connections/{id}/pairing-code, POST /connections/{id}/restart, POST /connections/{id}/logout, DELETE /connections/{id} |
„Als gelesen markieren“ ist ein Senden, kein Lesen
POST /messages/read benötigt whatsapp.send. Der Aufruf sieht nach einer
Leseoperation aus, doch er überträgt eine Bestätigung von Ihrer Nummer an
das Gerät des Kunden – er ist also ausgehend. Der Vorteil: Jeder Client, der
bereits senden darf, kann auch als gelesen markieren. Es ist kein neuer Scope
und keine erneute Zustimmung nötig.
Die Auflösung erfolgt live
Scopes und die Liste der erreichbaren Verbindungen werden bei jeder Anfrage aufgelöst. Im Token wird nichts zwischengespeichert, und nichts muss erneuert werden. Daraus folgen zwei Dinge:
- Wenn Sie einen Schlüssel widerrufen oder seine Scopes einschränken, gilt das ab dem nächsten Aufruf.
- Eine soeben erstellte Verbindung ist beim nächsten Aufruf sichtbar. Es gibt keine Verzögerung bei der Verteilung, und es muss nichts neu ausgestellt werden.
Unzureichender Scope
Zugangsdaten, denen der für einen Endpunkt erforderliche Scope fehlt, erhalten
403 insufficient_scope. Werten Sie den Code aus, nicht den Status – 403
liefert auch die Ablehnung durch eine IP-Allowlist (ip_not_allowed), und die
beiden Fälle erfordern gegensätzliche Lösungen: Im einen Fall bearbeiten Sie die
Scopes des Schlüssels, im anderen fügen Sie eine Adresse hinzu. Siehe
Fehler und Idempotenz.
Fordern Sie weniger an
Der Scope, den Sie nicht vergeben, ist derjenige, der sich nicht missbrauchen
lässt, falls der Schlüssel in falsche Hände gerät. Ein reiner Reporting-Job
braucht whatsapp.read und sonst nichts; ein Sender für Benachrichtigungen
braucht whatsapp.send; nur ein Provisioning-Flow benötigt whatsapp.manage,
womit sich Verbindungen löschen lassen.
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.
Fehler & Idempotenz
Verzweigen Sie nach dem Fehlercode, nicht nach dem Status. Und machen Sie jeden Wiederholungsversuch, der Geld kostet, sicher.