API-Referenz der DobroDesk-Integration für Zapier

Basis-URL und Zugriffsschlüssel

Die Zapier-Integration verwendet die produktive HTTPS-API unter https://dobrodesk.com/api/v1. Senden Sie bei jeder Anfrage einen aktiven DobroDesk-API-Schlüssel im Authorization-Header.

Erstellen Sie einen Schlüssel für Automatisierungen und einen weiteren für interne Notizen. Der Auslöser-Schlüssel kann Metadaten zu Gesprächen im gesamten Arbeitsbereich lesen, darunter IDs, Inbox, Status, Quellkanal und Zeitstempel. Er kann weder Kundennachrichten noch Anhänge lesen. Eine Inbox-Auswahl filtert zugestellte Ereignisse, schränkt den Metadatenzugriff jedoch nicht ein. Mit dem Notizschlüssel können Sie einem Gespräch im Arbeitsbereich eine interne Notiz hinzufügen.

Zapier-Schlüssel mit festgelegtem Zweck sind die empfohlene Self-Service-Option. Der Auslöser-Schlüssel verwendet conversations:read und funktioniert auf den beschriebenen Auslöser-Endpunkten sowie bei der Verbindungsprüfung. Der Notizschlüssel verwendet conversations:write und funktioniert auf dem Endpunkt für interne Notizen sowie bei der Verbindungsprüfung. Zweckgebundene Schlüssel werden an anderen API-Endpunkten mit HTTP 403 und dem Code api_token_purpose_forbidden abgelehnt. Ein aktiver allgemeiner REST-API-Schlüssel wird auf diesen Zapier-Endpunkten ebenfalls gemäß seinen üblichen Scopes akzeptiert: Für die Verbindungsprüfung ist kein Scope erforderlich, Lese- und Abonnement-Endpunkte benötigen conversations:read und das Hinzufügen einer Notiz benötigt conversations:write. Allgemeine Schlüssel behalten ihren normalen REST-API-Zugriff. Verwenden Sie für möglichst geringe Berechtigungen die zweckgebundenen Schlüssel.

Behandeln Sie einen Zugriffsschlüssel wie ein Passwort. Fügen Sie ihn weder in eine URL noch in Browsercode, gemeinsam genutzte Protokolle oder eine Zapier-Webhook-Ziel-URL ein.

Authorization: Bearer dd_live_<dedicated-access-key>

Verbindung prüfen

GET /zapier/connection prüft einen aktiven REST-API-Schlüssel und identifiziert den zugehörigen Arbeitsbereich und die Verbindung. Der Endpunkt akzeptiert allgemeine Schlüssel und beide zweckgebundenen Zapier-Schlüssel. Ein zusätzlicher Scope ist nicht erforderlich. Bei Erfolg wird HTTP 200 zurückgegeben.

Das Objekt data enthält workspaceId, tokenId, scopes, workspaceName und connectionName. Der Endpunkt gibt den Zugriffsschlüssel nicht zurück.

GET https://dobrodesk.com/api/v1/zapier/connection
Authorization: Bearer dd_live_<dedicated-access-key>

{
  "data": {
    "workspaceId": "<workspaceId>",
    "tokenId": "<tokenId>",
    "scopes": ["conversations:read"],
    "workspaceName": "<workspaceName>",
    "connectionName": "<connectionName>"
  }
}

Inbox-Auswahl und Gesprächsbeispiele lesen

GET /zapier/inboxes?page=0&limit=100 gibt eine Seite mit Inbox-Auswahlmöglichkeiten im Array data zurück. Jeder Eintrag enthält id und name. page ist eine Ganzzahl von 0 bis 10.000 und hat den Standardwert 0. limit ist eine Ganzzahl von 1 bis 100 und hat den Standardwert 100.

GET /zapier/conversations?limit=3&inboxId=<inboxId> gibt Gesprächsmetadaten für den Testschritt im Zapier-Editor zurück. inboxId ist optional und muss als nicht leere Zeichenfolge übergeben werden. limit ist eine Ganzzahl von 1 bis 100 und hat den Standardwert 10. Jeder Eintrag enthält id, workspaceId, conversationId, status, sourceChannel und createdAt sowie bei Bedarf inboxId. id entspricht der Gesprächs-ID. Kundennachrichten und Anhänge werden nicht zurückgegeben.

Für beide Endpunkte ist conversations:read erforderlich. Verwenden Sie den zweckgebundenen Auslöser-Schlüssel oder einen aktiven allgemeinen REST-API-Schlüssel mit diesem Scope. In der Ausgabe eines Live-Auslösers kennzeichnet eventId das Ereignis und occurredAt dessen Zeitpunkt. Die Gesprächs-ID bleibt die stabile Kennung des Gesprächs.

GET /api/v1/zapier/inboxes?page=0&limit=100
GET /api/v1/zapier/conversations?limit=3&inboxId=<inboxId>

Ein New-Conversation-Abonnement erstellen

POST /zapier/subscriptions registriert das REST-Hook-Ziel von Zapier und erfordert conversations:read. Verwenden Sie den zweckgebundenen Auslöser-Schlüssel oder einen aktiven allgemeinen REST-API-Schlüssel mit dieser Berechtigung. Im JSON-Body ist targetUrl erforderlich. inboxId ist optional und kann als Zeichenfolge angegeben werden. Ohne inboxId erhält das Abonnement neue Unterhaltungen aus allen Posteingängen. Pro Arbeitsbereich sind bis zu 100 aktive Webhook-Abonnements für Zapier und andere Webhook-Integrationen möglich. Bei Erfolg gibt die API HTTP 200 mit der Abonnement-ID in data.id zurück.

DobroDesk akzeptiert nur HTTPS-Ziele mit dem exakten Host hooks.zapier.com. Fügen Sie keine Zugangsdaten, keinen expliziten Port und kein URL-Fragment hinzu. Den Pfad und die Abfrageparameter stellt Zapier bereit. Die vollständige Ziel-URL ist ein Geheimnis. Bewahren Sie sie sicher auf. Ein Posteingangsfilter ändert nur, welche Ereignisse zugestellt werden. Der Auslöser-Schlüssel kann weiterhin die beschriebenen Metadaten im gesamten Arbeitsbereich lesen.

Bei jedem neuen Gespräch sendet DobroDesk einen POST an die Ziel-URL mit den Headern X-DobroDesk-Delivery und X-DobroDesk-Event: conversation.created sowie einem JSON-Body mit deliveryId. Der Callback ist nicht mit HMAC signiert. Der Zapier-Auslöser prüft, ob die Zustell-ID im Header X-DobroDesk-Delivery mit deliveryId im Anfrage-Body übereinstimmt, und liest das kanonische Ereignis anschließend mit seinem authentifizierten Schlüssel von DobroDesk.

POST /api/v1/zapier/subscriptions
Authorization: Bearer dd_live_<trigger-access-key>
Content-Type: application/json

{
  "targetUrl": "https://hooks.zapier.com/<Zapier-assigned-path>",
  "inboxId": "<inboxId>"
}

{
  "data": {
    "id": "<subscriptionId>"
  }
}

Ein zugestelltes Ereignis lesen und abbestellen

GET /zapier/events/<deliveryId> erfordert conversations:read und denselben Schlüssel, mit dem das Abonnement erstellt wurde. Bei Erfolg wird HTTP 200 mit dem kanonischen Ereignis zurückgegeben, sofern das Abonnement aktiv ist. Die Antwort enthält data.id, data.type, data.workspaceId, data.occurredAt und data.data. Der Ereignistyp ist conversation.created. Das verschachtelte data-Objekt enthält conversationId, optional inboxId, status, sourceChannel und createdAt.

Der Live-Auslöser zeigt die Ereignis-ID als eventId und den Ereigniszeitpunkt als occurredAt an. Die API gibt nur Gesprächsmetadaten zurück, keine Kundennachrichten oder Anhänge.

DELETE /zapier/subscriptions/<subscriptionId> erfordert conversations:read und denselben Schlüssel, mit dem das Abonnement erstellt wurde. Der Endpunkt deaktiviert das Abonnement und gibt bei Erfolg HTTP 200, data.id sowie data.disabled mit dem Wert true zurück. Für ein fehlendes, inaktives oder mit diesem Schlüssel nicht zugängliches Abonnement oder Ereignis wird 404 zurückgegeben. Schalten Sie den Zap aus, bevor Sie den Schlüssel trennen, damit Zapier das Abonnement ordnungsgemäß beenden kann.

GET /api/v1/zapier/events/<deliveryId>
Authorization: Bearer dd_live_<trigger-access-key>

DELETE /api/v1/zapier/subscriptions/<subscriptionId>
Authorization: Bearer dd_live_<trigger-access-key>

Eine interne Notiz hinzufügen

POST /conversations/<conversationId>/notes erfordert conversations:write. Verwenden Sie den zweckgebundenen Notizschlüssel oder einen aktiven allgemeinen REST-API-Schlüssel mit diesem Scope. Senden Sie einen JSON-Body mit bodyText. Nach dem Entfernen äußerer Leerzeichen muss der Text 1 bis 20.000 Zeichen lang sein. Bei Erfolg wird HTTP 200 mit data.id und data.status zurückgegeben. Nach dem Speichern hat status den Wert saved. Die Aktion fügt eine für das Team sichtbare Notiz hinzu und sendet keine Kundenantwort.

Senden Sie bei jedem Schreibvorgang einen Idempotency-Key. Ordnen Sie in der Zapier-Aktion Source event or operation ID einem nicht leeren, stabilen Wert mit höchstens 1.024 Zeichen zu. Der Connector hasht diesen Wert mit SHA-256 und sendet einen Schlüssel mit dem Präfix zapier-note- und 64 kleingeschriebenen Hexadezimalzeichen. Der Wert des Idempotency-Key-Headers muss 1 bis 200 Zeichen umfassen und darf nur ASCII-Buchstaben und -Ziffern sowie `.`, `_`, `:` und `-` enthalten. Verwenden Sie bei einem erneuten Versuch dieselbe Access-Key-Verbindung, denselben Idempotency-Key, dieselbe conversationId und denselben Notiztext. DobroDesk speichert das Ergebnis 365 Tage lang. Es ist an den Arbeitsbereich und die Identität des Zugriffsschlüssels gebunden. Dieselbe Idempotenzkennung mit einer anderen conversationId oder einem anderen Notiztext führt zu HTTP 409 mit dem Code idempotency_conflict. Gibt ein erneuter Versuch idempotency_in_progress zurück, warten Sie kurz. Wiederholen Sie den Vorgang mit derselben Quell-ID, derselben conversationId und demselben Notiztext. Der Connector garantiert keine automatischen Wiederholungsversuche.

POST /api/v1/conversations/<conversationId>/notes
Authorization: Bearer dd_live_<note-access-key>
Idempotency-Key: zapier-note-<sha256-of-source-reference>
Content-Type: application/json

{
  "bodyText": "Internal update from an approved automation."
}

{
  "data": {
    "id": "<noteId>",
    "status": "saved"
  }
}

Fehler und Ratenlimits

Ein fehlender, ungültiger, abgelaufener oder widerrufener Schlüssel führt zu HTTP 401. Ein falscher Schlüsselzweck führt zu HTTP 403 mit dem Code api_token_purpose_forbidden. Bei einem fehlenden Scope wird HTTP 403 mit dem Code insufficient_scope und requiredScope zurückgegeben.

Autorisierte API-Anfragen sind auf 300 pro Minute und Schlüssel begrenzt. Die Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Bei Überschreitung gibt DobroDesk HTTP 429 mit dem Code rate_limit_exceeded und dem Header Retry-After zurück. Das Limit ist keine Garantie für Verfügbarkeit oder Zustellzeit. Eine gültige Anfrage kann bei einer vorübergehenden Dienststörung auch HTTP 5xx zurückgeben.

• GET /zapier/connection: zapier_connection_unavailable (503).
• GET /zapier/inboxes und GET /zapier/conversations: zapier_query_invalid (400).
• POST /zapier/subscriptions: zapier_subscription_invalid oder zapier_target_url_invalid (400), inbox_not_found (404), zapier_subscription_conflict oder zapier_subscription_limit_reached (409) und zapier_subscription_unavailable (503). Ein Konflikt bedeutet, dass dieses Ziel bereits mit anderen Einstellungen aktiv ist. Pro Arbeitsbereich gilt ein Limit von 100 aktiven Webhook-Abonnements.
• DELETE /zapier/subscriptions/<subscriptionId>: zapier_subscription_not_found (404).
• GET /zapier/events/<deliveryId>: zapier_event_not_found (404).
• POST /conversations/<conversationId>/notes: conversation_id_required (400), conversation_not_found (404), idempotency_key_required oder internal_note_body_invalid (400) sowie idempotency_conflict oder idempotency_in_progress (409). idempotency_in_progress bedeutet, dass dieselbe Anfrage noch verarbeitet wird.

HTTP 403
data.code = api_token_purpose_forbidden

HTTP 429
data.code = rate_limit_exceeded