Довідник API для підключення DobroDesk до Zapier

Базова адреса API та ключі доступу

Інтеграція Zapier використовує робочий HTTPS API за адресою https://dobrodesk.com/api/v1. Передавайте активний ключ доступу DobroDesk у заголовку Authorization кожного запиту.

Створіть окремий ключ для запуску автоматизацій і ще один для додавання внутрішніх нотаток. Ключ тригера може читати метадані розмов у всьому робочому просторі: ідентифікатори, скриньку, стан, канал і часові позначки. Він не читає текст повідомлень клієнтів або вкладення. Фільтр скриньки обмежує доставлені події, але не доступ до метаданих. Ключ нотаток може додавати внутрішню нотатку до розмови в робочому просторі.

Спеціальні ключі з метою доступу Zapier рекомендовано для самостійного підключення. Ключ тригера має conversations:read і працює з описаними маршрутами тригера та перевіркою підключення. Ключ нотаток має conversations:write і працює з маршрутом внутрішніх нотаток та перевіркою підключення. Спеціальні ключі відхиляються від інших маршрутів API з HTTP 403 і кодом api_token_purpose_forbidden. Звичайний активний REST API-ключ також приймається на цих маршрутах Zapier згідно зі своїми дозволами: перевірка підключення не вимагає області доступу, маршрути читання й керування підписками вимагають conversations:read, а додавання нотатки — conversations:write. Звичайні ключі зберігають свій звичайний доступ до REST API, тому для найменших привілеїв використовуйте спеціальні ключі.

Ставтеся до ключа доступу як до пароля. Не додавайте його до URL-адреси, коду браузера, спільного журналу чи URL вебхука Zapier.

Authorization: Bearer dd_live_<dedicated-access-key>

Перевірте підключення

GET /zapier/connection перевіряє активний REST API-ключ і визначає його робочий простір та підключення. Маршрут приймає звичайний ключ і спеціальні ключі Zapier. Додаткова область доступу не потрібна. У разі успіху повертається HTTP 200.

Об'єкт data містить workspaceId, tokenId, scopes, workspaceName і connectionName. Маршрут не повертає сам ключ доступу.

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

Отримайте скриньки й приклади розмов

GET /zapier/inboxes?page=0&limit=100 повертає сторінку скриньок у масиві data. Кожен елемент має id і name. page — ціле число від 0 до 10 000, типове значення — 0. limit — ціле число від 1 до 100, типове значення — 100.

GET /zapier/conversations?limit=3&inboxId=<inboxId> повертає метадані розмов для перевірки кроку в редакторі Zapier. Параметр inboxId необов'язковий, але якщо його передано, це має бути непорожній рядок. limit — ціле число від 1 до 100, типове значення — 10. Кожен результат містить id, workspaceId, conversationId, status, sourceChannel і createdAt, а також inboxId, якщо його задано. id збігається з ідентифікатором розмови. Текст повідомлень клієнтів і вкладення не повертаються.

Для обох маршрутів потрібна область доступу conversations:read. Використовуйте спеціальний ключ тригера або активний звичайний REST API-ключ із цією областю доступу. У події активного тригера eventId позначає подію, а occurredAt містить її час. Conversation ID залишається сталим ідентифікатором розмови.

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

Створіть підписку на New Conversation

POST /zapier/subscriptions реєструє ціль REST Hook у Zapier і потребує conversations:read. Використовуйте спеціальний ключ тригера або активний звичайний REST API-ключ із цією областю доступу. У JSON-тілі обов'язково передайте targetUrl. Параметр inboxId можна передати рядком, але вказувати його не обов'язково. Якщо пропустити це поле, підписка отримуватиме нові розмови з усіх скриньок. У робочому просторі може бути до 100 активних підписок на вебхуки для Zapier та інших інтеграцій вебхуків. У разі успіху повертається HTTP 200 та ідентифікатор підписки в data.id.

DobroDesk приймає лише HTTPS-цілі з точним доменом hooks.zapier.com. Не додавайте облікові дані, явний порт чи фрагмент URL. Шлях і параметри запиту надає Zapier. Цільова URL-адреса є секретом, тому не розголошуйте її. Фільтр скриньки змінює лише доставку подій. Ключ тригера й далі має доступ до метаданих у всьому робочому просторі.

Для кожної нової розмови DobroDesk надсилає POST на цільову URL-адресу із заголовками X-DobroDesk-Delivery і X-DobroDesk-Event: conversation.created та JSON-тілом з deliveryId. Зворотний виклик не підписано HMAC. Тригер Zapier перевіряє, що ID доставки в X-DobroDesk-Delivery збігається з deliveryId у тілі запиту, а потім отримує канонічну подію з 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>"
  }
}

Отримайте подію та відпишіться

Для GET /zapier/events/<deliveryId> потрібні conversations:read і той самий ключ, яким створено підписку. Маршрут у разі успіху повертає HTTP 200 і канонічну подію, коли підписка активна. Відповідь містить data.id, data.type, data.workspaceId, data.occurredAt і data.data. Тип події — conversation.created. Вкладений об'єкт data містить conversationId, необов'язковий inboxId, status, sourceChannel і createdAt.

Активний тригер показує ID події як eventId, а її час — як occurredAt. API повертає лише метадані розмови, без тексту повідомлень клієнта й вкладень.

DELETE /zapier/subscriptions/<subscriptionId> потребує conversations:read і того самого ключа, яким створено підписку. Маршрут вимикає підписку й у разі успіху повертає HTTP 200, data.id та data.disabled зі значенням true. Якщо підписку або подію не знайдено, вона неактивна чи недоступна цьому ключу, повертається 404. Перед від'єднанням ключа вимкніть Zap, щоб Zapier міг коректно скасувати підписку.

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>

Додайте внутрішню нотатку

Для POST /conversations/<conversationId>/notes потрібна область доступу conversations:write. Використовуйте спеціальний ключ нотаток або активний звичайний REST API-ключ із цією областю доступу. Передайте JSON-тіло з полем bodyText. Після обрізання пробілів текст має містити від 1 до 20 000 символів. У разі успіху повертається HTTP 200, а data.id містить ідентифікатор нотатки й data.status має значення saved після її збереження. Ця дія додає нотатку для колег і не надсилає відповідь клієнту.

Для кожного запису передавайте Idempotency-Key. У дії Zapier зіставте Source event or operation ID з непорожнім сталим значенням завдовжки до 1 024 символів. Інтеграція хешує його за SHA-256 і надсилає ключ із префіксом zapier-note- та 64 малими шістнадцятковими символами. Заголовок Idempotency-Key має містити від 1 до 200 символів: лише літери й цифри ASCII та символи `.`, `_`, `:` або `-`. Під час повтору використовуйте те саме підключення Access key, Idempotency-Key, conversationId і текст нотатки. DobroDesk зберігає результат 365 днів, прив'язуючи його до робочого простору й ідентичності ключа доступу. Повторне використання ключа з іншим conversationId або текстом нотатки повертає HTTP 409 з кодом idempotency_conflict. Якщо повторний запит повертає idempotency_in_progress, трохи зачекайте й повторіть його з тим самим ID джерела, conversationId і текстом нотатки. Інтеграція не гарантує автоматичного повтору.

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

Помилки й обмеження запитів

Відсутній, недійсний, прострочений або відкликаний ключ повертає HTTP 401. Невідповідна мета ключа повертає HTTP 403 з кодом api_token_purpose_forbidden. Якщо бракує області доступу, повертається HTTP 403 з кодом insufficient_scope і полем requiredScope.

Авторизовані запити API обмежено до 300 на хвилину для кожного ключа. У відповіді є заголовки X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset. Після перевищення ліміту DobroDesk повертає HTTP 429 з кодом rate_limit_exceeded і заголовком Retry-After. Ліміт не є гарантією доступності чи часу доставки. На коректний запит також може надійти HTTP 5xx, якщо сервіс тимчасово недоступний.

• GET /zapier/connection: zapier_connection_unavailable (503).
• GET /zapier/inboxes і GET /zapier/conversations: zapier_query_invalid (400).
• POST /zapier/subscriptions: zapier_subscription_invalid або zapier_target_url_invalid (400), inbox_not_found (404), zapier_subscription_conflict або zapier_subscription_limit_reached (409) та zapier_subscription_unavailable (503). Конфлікт означає, що ця ціль вже активна з іншими налаштуваннями. Ліміт робочого простору — 100 активних підписок на вебхуки.
• 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 або internal_note_body_invalid (400), idempotency_conflict або idempotency_in_progress (409). idempotency_in_progress означає, що такий самий запит ще обробляється.

HTTP 403
data.code = api_token_purpose_forbidden

HTTP 429
data.code = rate_limit_exceeded