Référence API pour connecter DobroDesk à Zapier

URL de base et clés d'accès

L'intégration Zapier utilise l'API HTTPS de production à l'adresse https://dobrodesk.com/api/v1. Envoyez une clé d'accès DobroDesk active dans l'en-tête Authorization de chaque requête.

Créez une clé pour lancer les automatisations et une autre pour ajouter des notes internes. La clé du déclencheur peut lire les métadonnées des conversations dans tout l'espace de travail, notamment les identifiants, la boîte de réception, le statut, le canal source et les horodatages. Elle ne peut pas lire le texte des messages client ni les pièces jointes. Le filtre de boîte de réception limite les événements transmis, mais pas l'accès aux métadonnées. La clé des notes peut ajouter une note interne à une conversation de l'espace de travail.

Les clés Zapier à usage défini sont le choix recommandé pour la connexion en libre-service. La clé du déclencheur utilise conversations:read et fonctionne sur les routes de déclencheur décrites ainsi que sur la vérification de connexion. La clé des notes utilise conversations:write et fonctionne sur la route de note interne ainsi que sur la vérification de connexion. Ces clés sont refusées sur les autres routes de l'API avec HTTP 403 et le code api_token_purpose_forbidden. Une clé REST API générique active est aussi acceptée sur ces routes Zapier selon ses scopes habituels : la vérification de connexion ne demande aucun scope, les routes de lecture et d'abonnement exigent conversations:read et l'ajout d'une note exige conversations:write. Les clés génériques conservent leur accès REST API habituel. Pour limiter les permissions, utilisez les clés à usage défini.

Traitez une clé d'accès comme un mot de passe. Ne l'incluez ni dans une URL, ni dans du code de navigateur, ni dans un journal partagé, ni dans l'URL cible d'un webhook Zapier.

Authorization: Bearer dd_live_<dedicated-access-key>

Vérifier la connexion

GET /zapier/connection vérifie une clé REST API active et identifie son espace de travail et sa connexion. La route accepte une clé générique ou l'une des clés Zapier à usage défini. Aucun scope supplémentaire n'est requis. En cas de succès, la réponse est HTTP 200.

L'objet data contient workspaceId, tokenId, scopes, workspaceName et connectionName. Cette route ne renvoie pas la clé d'accès.

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>"
  }
}

Lire les boîtes de réception et les exemples de conversations

GET /zapier/inboxes?page=0&limit=100 renvoie une page de boîtes de réception dans le tableau data. Chaque élément contient id et name. page est un entier compris entre 0 et 10 000, avec 0 par défaut. limit est un entier compris entre 1 et 100, avec 100 par défaut.

GET /zapier/conversations?limit=3&inboxId=<inboxId> renvoie les métadonnées de conversations pour tester l'étape dans l'éditeur Zapier. inboxId est facultatif et doit être une chaîne non vide lorsqu'il est fourni. limit est un entier compris entre 1 et 100, avec 10 par défaut. Chaque résultat contient id, workspaceId, conversationId, status, sourceChannel et createdAt, ainsi qu'inboxId le cas échéant. id correspond à l'identifiant de conversation. Le texte des messages client et les pièces jointes ne sont pas renvoyés.

Les deux routes exigent conversations:read. Utilisez la clé de déclencheur à usage défini ou une clé REST API générique active avec ce scope. Dans le résultat d'un déclencheur actif, eventId identifie l'événement et occurredAt indique son heure. L'identifiant de conversation reste la référence stable de la conversation.

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

Créer un abonnement New Conversation

POST /zapier/subscriptions enregistre la cible REST Hook de Zapier et exige conversations:read. Utilisez la clé de déclencheur à usage défini ou une clé REST API générique active avec ce scope. Le corps JSON doit contenir targetUrl et peut inclure inboxId sous forme de chaîne. Si inboxId est absent, l'abonnement reçoit les nouvelles conversations de toutes les boîtes de réception. Un espace de travail peut compter jusqu'à 100 abonnements webhook actifs pour Zapier et les autres intégrations webhook. En cas de succès, la réponse HTTP 200 contient l'identifiant d'abonnement dans data.id.

DobroDesk accepte uniquement les cibles HTTPS dont le nom d'hôte exact est hooks.zapier.com. N'incluez ni identifiants, ni port explicite, ni fragment d'URL. Zapier fournit le chemin et les paramètres de requête. L'URL cible complète est un secret opaque. Gardez-la privée. Le filtre de boîte de réception ne modifie que les événements livrés. La clé du déclencheur conserve l'accès aux métadonnées décrites dans tout l'espace de travail.

Pour chaque nouvelle conversation, DobroDesk envoie un POST à l'URL cible avec les en-têtes X-DobroDesk-Delivery et X-DobroDesk-Event: conversation.created, ainsi qu'un corps JSON contenant deliveryId. Le callback n'est pas signé avec HMAC. Le déclencheur Zapier vérifie que l'identifiant de livraison de l'en-tête X-DobroDesk-Delivery correspond à deliveryId dans le corps de la requête, puis récupère l'événement de référence auprès de DobroDesk avec sa clé authentifiée.

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>"
  }
}

Lire un événement transmis et se désabonner

GET /zapier/events/<deliveryId> exige conversations:read et la même clé que celle qui a créé l'abonnement. Si l'abonnement est actif, la route renvoie HTTP 200 et l'événement de référence. La réponse contient data.id, data.type, data.workspaceId, data.occurredAt et data.data. Le type est conversation.created. L'objet data imbriqué contient conversationId, inboxId facultatif, status, sourceChannel et createdAt.

Le déclencheur actif expose l'identifiant de l'événement sous eventId et son heure sous occurredAt. L'API ne renvoie que les métadonnées de la conversation, sans texte de message client ni pièce jointe.

DELETE /zapier/subscriptions/<subscriptionId> exige conversations:read et la même clé que celle qui a créé l'abonnement. La route le désactive et renvoie, en cas de succès, HTTP 200, data.id ainsi que data.disabled défini sur true. Une réponse 404 signifie que l'abonnement ou l'événement est introuvable, inactif ou inaccessible avec cette clé. Désactivez le Zap avant de déconnecter la clé pour que Zapier puisse annuler proprement l'abonnement.

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>

Ajouter une note interne

POST /conversations/<conversationId>/notes exige conversations:write. Utilisez la clé des notes à usage défini ou une clé REST API générique active avec ce scope. Envoyez un corps JSON avec bodyText. Une fois les espaces en début et en fin supprimés, le texte doit compter de 1 à 20 000 caractères. En cas de succès, la réponse HTTP 200 contient data.id et data.status, qui vaut saved une fois la note enregistrée. Cette action ajoute une note visible par l'équipe. Elle n'envoie pas de réponse au client.

Envoyez un Idempotency-Key pour chaque écriture. Dans l'action Zapier, associez Source event or operation ID à une valeur stable non vide de 1 024 caractères maximum. Le connecteur la hache avec SHA-256 et envoie une clé préfixée par zapier-note- suivie de 64 caractères hexadécimaux minuscules. La valeur de l'en-tête Idempotency-Key doit compter de 1 à 200 caractères et utiliser uniquement des lettres ou chiffres ASCII, ainsi que `.`, `_`, `:` ou `-`. Pour une nouvelle tentative, gardez la même connexion Access key, le même Idempotency-Key, la même conversationId et le même texte. DobroDesk conserve le résultat pendant 365 jours, lié à l'espace de travail et à l'identité de la clé d'accès. Réutiliser une clé avec une autre conversationId ou un autre texte renvoie HTTP 409 et le code idempotency_conflict. Si une nouvelle tentative renvoie idempotency_in_progress, attendez un instant puis relancez-la avec le même ID source, la même conversationId et le même texte. Le connecteur ne garantit pas de nouvelle tentative automatique.

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"
  }
}

Erreurs et limites de requêtes

Une clé absente, invalide, expirée ou révoquée renvoie HTTP 401. Un usage de clé non autorisé renvoie HTTP 403 avec le code api_token_purpose_forbidden. Si un scope manque, HTTP 403 renvoie le code insufficient_scope et requiredScope.

Les requêtes API autorisées sont limitées à 300 par minute et par clé. Les réponses incluent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. En cas de dépassement, DobroDesk renvoie HTTP 429 avec le code rate_limit_exceeded et Retry-After. Cette limite ne garantit ni la disponibilité ni un délai de livraison. Une requête valide peut également renvoyer HTTP 5xx si le service est temporairement indisponible.

• GET /zapier/connection : zapier_connection_unavailable (503).
• GET /zapier/inboxes et GET /zapier/conversations : zapier_query_invalid (400).
• POST /zapier/subscriptions : zapier_subscription_invalid ou zapier_target_url_invalid (400), inbox_not_found (404), zapier_subscription_conflict ou zapier_subscription_limit_reached (409), et zapier_subscription_unavailable (503). Un conflit signifie que cette même cible est déjà active avec des paramètres différents. La limite est de 100 abonnements webhook actifs par espace de travail.
• 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 ou internal_note_body_invalid (400), idempotency_conflict ou idempotency_in_progress (409). idempotency_in_progress indique que la même requête est encore en cours de traitement.

HTTP 403
data.code = api_token_purpose_forbidden

HTTP 429
data.code = rate_limit_exceeded