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.
Ein Workspace besitzt WhatsApp-Verbindungen. Ein API key wird für genau einen Workspace ausgestellt, und alles, was der Schlüssel sehen oder tun kann, bezieht sich nur auf diesen Workspace – ein Zugriff auf einen anderen ist nicht möglich.
Ein Schlüssel, ein Workspace, viele Verbindungen
Für eine Multi-Tenant-Anwendung ist das die passende Struktur:
- Ein API key, nicht einer pro Mandant. Erstellen Sie nicht für jeden Kunden einen eigenen Schlüssel.
- Ein
POST /connectionspro Mandant, auch für die allererste Verbindung, jeweils mit einem eigenen, neuenIdempotency-Key. - Leiten Sie eingehende Ereignisse anhand von
connection_idweiter – einer stabilen cuid, die in jeder REST-Antwort und jeder webhook-Payload enthalten ist. Ordnen Sie sie Ihrem eigenen Kundendatensatz zu: Wir vergeben die ID, Sie führen die Zuordnung. - Neue Verbindungen sind sofort nutzbar. Die Verbindungsliste des Schlüssels wird bei jeder Anfrage live ermittelt, nach dem Anlegen muss also nichts aktualisiert werden.
Zwei Arten von Workspaces
Eigenständiger Workspace
Wird angelegt, wenn Sie sich auf developers.wasync.app registrieren. Die API ist das gesamte Produkt: Sie erstellen Verbindungen über REST, und jede Verbindung hat ihre eigene Lizenz.
Bitrix24-Portal
Wird angelegt, wenn WASync auf einem Bitrix24-Portal installiert wird. Verbindungen werden vom Portaladministrator in WASync erstellt, und der API-Zugriff auf eine Nummer ist ein kostenpflichtiges Add-on.
Der Unterschied zeigt sich an genau zwei Stellen. Es lohnt sich, sie zu kennen, bevor Sie Code gegen den falschen Typ schreiben:
Verbindungen erstellen. POST /connections gibt es nur für eigenständige Workspaces. Auf einem Bitrix24-Portal
antwortet der Aufruf mit 403 forbidden_portal_kind – dort erstellt der Portaladministrator
Verbindungen stattdessen in der WASync-Oberfläche. Alle anderen Endpunkte verhalten sich
in beiden Fällen gleich.
Was eine Verbindung erreichbar macht. In einem eigenständigen Workspace ist es die
eigene Lizenz der Verbindung (trial oder kostenpflichtig). Auf einem Bitrix24-Portal
bezahlt das Abonnement des Portals die Nummer im CRM. Um dieselbe Nummer
über die API zu erreichen, ist zusätzlich das API-Add-on nötig, für 12 $ pro Nummer und
Monat. Ohne dieses Add-on erscheint die Verbindung schlicht nicht in GET /connections.
Einstieg
Mit einem API key gibt es keinen Einrichtungsschritt: Der Schlüssel wird direkt für Ihren
Workspace ausgestellt, sodass POST /connections die erste Verbindung genauso
problemlos anlegt wie die zehnte.
Bei einer OAuth-Freigabe ist es konstruktionsbedingt anders – sie wird immer nur für bereits bestehende Verbindungen ausgestellt. Eine reine OAuth-Integration kann daher nicht die erste Verbindung eines Workspaces anlegen. Aus diesem Grund beginnt jede Schnellstart-Anleitung hier mit einem Schlüssel.