На головну

Інтеграція MARREK зі своїм продуктом

API MARREK дає вашому ПЗ доступ до тих самих даних, що й у кабінеті: читати діалоги й надсилати відповіді, синхронізувати ліди з CRM, керувати товарами та базою знань, налаштовувати ШІ та вивантажувати аналітику. Вебхуки надсилають вам нові повідомлення й ліди в ту саму мить, коли вони з’являються.

Швидкий старт

Потрібен акаунт MARREK на тарифі, що включає API (зараз це Business і Pro). Створювати ключі та вебхуки може лише власник акаунта.

  • У кабінеті відкрийте «Розробникам» → «API-ключі» й натисніть «Створити ключ». Оберіть, що дозволено ключу, і за бажанням — до яких проєктів він має доступ. Скопіюйте ключ (він починається з mk_live_) — його показують один раз.
  • Звертайтеся до API зі свого сервера, передаючи ключ як bearer-токен. Спершу отримайте список проєктів:
curl https://marrek.app/api/public/v1/projects \
  -H "Authorization: Bearer mk_live_YOUR_KEY"

Відповідь

{
  "data": [
    { "id": 42, "name": "Shoe Store", "slug": "shoe-store-x1y2z3", "ai_enabled": true }
  ]
}

Далі читайте діалоги проєкту (передайте його id в X-Project-Id) і надішліть відповідь:

curl "https://marrek.app/api/public/v1/threads?per_page=20&channel=telegram" \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "X-Project-Id: 42"
curl -X POST https://marrek.app/api/public/v1/threads/1001/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" \
  -H "X-Project-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello! Your order has shipped."}'

Відповідь

{
  "data": {
    "id": 5120,
    "thread_id": 1001,
    "direction": "outbound",
    "sender_type": "manager",
    "content": "Hello! Your order has shipped.",
    "delivery_status": "pending",
    "metadata": { "source": "api", "api_key_id": 7 },
    "attachments": [],
    "created_at": "2026-09-29T12:00:00.000000Z"
  }
}
Зберігайте ключі лише на сервері. Ніколи не вставляйте їх у веб-сторінку, мобільний застосунок чи публічний репозиторій — хто має ключ, може все, що він дозволяє. Якщо ключ витік, відкличте його в кабінеті — він одразу перестане працювати.

Автентифікація

Передавайте ключ у заголовку Authorization: Authorization: Bearer mk_live_… . Базова адреса — https://marrek.app/api/public/v1. Усі запити й відповіді — JSON по HTTPS.

Ключ діє від імені власника акаунта, який його створив. Він працює, доки ця людина активна й досі володіє акаунтом; якщо щось із цього перестає бути правдою, ключ перестає працювати.

Статусerror.codeЗначення
401invalid_api_keyКлюч відсутній, має неправильний формат або невідомий
401api_key_revokedКлюч відкликано в кабінеті
401api_key_expiredТермін дії ключа минув
401api_key_disabledВласник, що створив ключ, більше не має доступу
402plan_limit_exceeded (error.limit = api_access)Тариф акаунта не включає API — перевіряється на кожному запиті
429too_many_auth_failuresЗабагато неправильних ключів з вашої IP — зачекайте й повторіть

Проєкти

В акаунті може бути кілька проєктів (робочих просторів): у кожного свої діалоги, ліди, товари, база знань і налаштування ШІ. Кожен запит працює рівно в одному проєкті.

  • Передавайте id проєкту в заголовку X-Project-Id. GET /projects повертає id, доступні вашому ключу.
  • Якщо ключ має доступ лише до одного проєкту, заголовок можна не передавати — його буде обрано автоматично.
  • Якщо доступних кілька, а ви не передали жодного, відповідь — 409 з error.code = project_required.
  • Проєкт поза списком дозволених для ключа дає 403 project_forbidden.

Формат помилки

{
  "message": "Select a project with the X-Project-Id header.",
  "error": { "code": "project_required" }
}

Права доступу (scopes)

Створюючи ключ, ви для кожної області обираєте: без доступу, читання або читання й запис. «Запис» завжди включає «читання». Запит поза правами ключа отримує 403 insufficient_scope, а у відповіді вказано, що було потрібно.

ScopeДозволяє
dialogs:readПереглядати діалоги, читати повідомлення
dialogs:writeНадсилати повідомлення, позначати прочитаним, змінювати перемикач ШІ та статус ліда діалогу, завантажувати вкладення
leads:read / leads:writeЧитати й експортувати ліди / редагувати та видаляти їх
catalog:read / catalog:writeЧитати товари й категорії / створювати, редагувати, видаляти
knowledge:read / knowledge:writeЧитати / керувати документами бази знань
ai_settings:read / ai_settings:writeЧитати / змінювати промпт і поведінку ШІ
analytics:readЧитати статистику

Давайте кожній інтеграції мінімум потрібного. Ключу, що лише годує вашу BI-систему, достатньо analytics:read.

Запити, помилки та ліміти

  • Пагінація — списки приймають page і per_page (1–100) та повертають { data, links, meta }. Історія повідомлень гортається назад через before_id і limit.
  • Фільтри — діалоги та ліди приймають ті самі фільтри, що й кабінет (channel, status, q, date_from, date_to …); див. довідник.
  • Товари — category_id повертає товари цієї категорії та всіх її підкатегорій; q і is_active додатково звужують список.
  • Ліміт — 120 запитів на хвилину на ключ. Кожна відповідь містить X-RateLimit-Limit і X-RateLimit-Remaining; при перевищенні — 429 із Retry-After.
  • Час — ISO 8601 в UTC. Передайте X-Timezone (наприклад Europe/Kyiv), щоб фільтри за днями та аналітика рахувались за вашу календарну добу; часовий пояс, закріплений у налаштуваннях власника ключа, має пріоритет.
СтатусКоли
400X-Project-Id не є числом (invalid_project_id)
401 / 403Див. «Автентифікація» та «Права доступу»
404Ресурсу немає в цьому проєкті (або він належить іншому)
409project_required або конфлікт стану, наприклад ai_enable_conflict
422Помилка валідації — errors містить кожне поле
429Перевищено ліміт запитів

Помилки валідації

{
  "message": "The name field is required.",
  "errors": { "name": ["The name field is required."] }
}

Надсилання повідомлення повертає 201 з delivery_status: pending — повідомлення поставлено в чергу на канал клієнта. Фінальний статус (delivered або failed) прийде вебхуком message.updated, або перечитайте його з діалогу.

Надсилання вкладення

# 1. Ask for an upload URL
curl -X POST https://marrek.app/api/public/v1/media/upload-url \
  -H "Authorization: Bearer mk_live_YOUR_KEY" -H "X-Project-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{"filename": "photo.jpg", "content_type": "image/jpeg", "size_bytes": 204800}'
# → { "url": "https://…", "headers": { "Content-Type": "image/jpeg" }, "key": "tenants/42/outgoing/….jpg", "kind": "image" }

# 2. PUT the file to that url, sending exactly the returned headers
curl -X PUT "<url>" -H "Content-Type: image/jpeg" --data-binary @photo.jpg

# 3. Send the message, referencing the key
curl -X POST https://marrek.app/api/public/v1/threads/1001/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY" -H "X-Project-Id: 42" \
  -H "Content-Type: application/json" \
  -d '{"content": "Here is the photo", "attachment_key": "tenants/42/outgoing/….jpg",
       "attachment_kind": "image", "attachment_mime_type": "image/jpeg", "attachment_size_bytes": 204800}'

Вебхуки

Замість опитування дозвольте MARREK дзвонити вам. У «Розробникам» → «Вебхуки» додайте адресу ендпоінта на вашому сервері, оберіть події та проєкти й скопіюйте секрет підпису (його показують один раз). Після цього MARREK надсилатиме HTTPS POST на кожну відповідну подію.

Адреса має бути публічною https://. Localhost і приватні мережі заборонені. Під час розробки відкрийте свій комп’ютер через тунель (ngrok, Cloudflare Tunnel …). Натисніть «Надіслати тест», щоб перевірити, що ендпоінт відповідає, ще до справжніх подій.

Кожен запит виглядає так:

POST /marrek/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Marrek-Webhooks/1
X-Marrek-Event-Id: 0198c7a1-5b3e-7c11-9f0a-2d6e4b8a1c33
X-Marrek-Event-Type: message.received
X-Marrek-Timestamp: 1790683200
X-Marrek-Delivery-Attempt: 1
X-Marrek-Signature: t=1790683200,v1=5f2b6c…e91a

Тіло message.received (скорочено)

{
  "id": "0198c7a1-5b3e-7c11-9f0a-2d6e4b8a1c33",
  "type": "message.received",
  "api_version": "v1",
  "created_at": "2026-09-29T12:00:00Z",
  "account_id": 7,
  "project_id": 42,
  "data": {
    "object_type": "message",
    "object": {
      "id": 5119,
      "thread_id": 1001,
      "direction": "inbound",
      "sender_type": "customer",
      "content": "Do you have size 42?",
      "has_attachments": false,
      "attachments": [],
      "delivery_status": "received",
      "created_at": "2026-09-29T12:00:00.000000Z"
    },
    "thread": {
      "id": 1001,
      "channel": "telegram",
      "customer_name": "Olena",
      "customer_username": "olena_k",
      "status": "unread",
      "ai_enabled": true,
      "lead_status": null
    }
  }
}

Об’єкт усередині data — це рівно те, що повертає відповідний REST-ендпоінт, тож форма одна. Події повідомлень також містять діалог у data.thread, щоб ви знали, хто написав, без другого запиту. Події «updated» додають data.changes зі старим і новим значенням кожного зміненого поля:

thread.updated

{
  "type": "thread.updated",
  "data": {
    "object_type": "thread",
    "object": { "id": 1001, "lead_status": "ready_to_close", "ai_enabled": false },
    "changes": {
      "lead_status": { "from": "interested", "to": "ready_to_close" },
      "ai_enabled": { "from": true, "to": false }
    }
  }
}
ПодіяКоли
message.receivedКлієнт написав повідомлення (Telegram, Instagram, веб-віджет)
message.sentСтворено відповідь — ШІ, менеджером або через API
message.updatedПовідомлення змінилось: статус доставки або вкладення завантажилось (тепер має url)
thread.createdРозпочався новий діалог
thread.updatedЗмінився статус діалогу, перемикач ШІ, відповідальний, статус ліда чи закриття
lead.createdОтримано перші контактні дані клієнта
lead.updatedЛід оновлено ШІ або відредаговано людиною
lead.deletedЛід видалено (у вмісті — його останній стан)

Перевірка підпису

На вашу адресу може надіслати POST будь-хто, тож перш ніж довіряти запиту, перевірте, що він справді від MARREK. Кожен запит містить X-Marrek-Signature: t=<unix-час>,v1=<hex>. Підпис — це HMAC-SHA256 із секретом вашого ендпоінта від рядка "<t>.<сире тіло запиту>".

  • Використовуйте сире тіло рівно в тому вигляді, в якому воно прийшло — розбір і повторна серіалізація JSON змінюють байти.
  • Відхиляйте запити, чий час відрізняється від вашого більш ніж на 5 хвилин (захист від повторного відтворення).
  • Порівнюйте функцією з постійним часом виконання.
  • Під час зміни секрету заголовок містить v1= і для старого, і для нового секрету; приймайте запит, якщо збігається будь-який.
<?php
// $secret is the whsec_… value shown when you created the endpoint.
$payload   = file_get_contents('php://input');          // the RAW body — do not decode it first
$header    = $_SERVER['HTTP_X_MARREK_SIGNATURE'] ?? '';

$timestamp = null;
$signatures = [];
foreach (explode(',', $header) as $piece) {
    [$key, $value] = array_pad(explode('=', trim($piece), 2), 2, '');
    if ($key === 't') { $timestamp = (int) $value; }
    if ($key === 'v1') { $signatures[] = $value; }       // several while a secret is being rotated
}

if ($timestamp === null || abs(time() - $timestamp) > 300) {
    http_response_code(400); exit('stale or malformed timestamp');
}

$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

$valid = false;
foreach ($signatures as $signature) {
    $valid = $valid || hash_equals($expected, $signature);  // constant-time compare
}
if (! $valid) { http_response_code(401); exit('bad signature'); }

$event = json_decode($payload, true);
// De-duplicate on $event['id'], enqueue the work, and answer quickly:
http_response_code(200);

Доставка, повтори та надійність

Відповідайте будь-яким статусом 2xx протягом 10 секунд — справжню роботу виконуйте в черзі. Доставка «принаймні один раз»: та сама подія може прийти більше ніж раз, тому дедублікуйте за id події (він також іде в X-Marrek-Event-Id) — він однаковий на кожному повторі. Порядок подій не гарантується — орієнтуйтеся на created_at і власні часові мітки об’єкта.

Ваша відповідьЩо робить MARREK
2xxДоставлено — готово
408, 429, 5xx, таймаут, помилка мережі чи TLSПовторює з наростаючими паузами (приблизно 30 с, 1 хв, 2 хв … до 1 год), до 10 спроб за 24 години; враховує Retry-After
Інші 4xx (400, 401, 403, 404, 410, 422 …)Не повторюється — вважається проблемою налаштування. Виправте й повторіть із журналу доставок
3xxПеренаправлення не виконуються — вкажіть кінцевий URL
  • Якщо ендпоінт постійно відповідає помилками, його призупиняють на кілька хвилин, щоб не навантажувати, а після 72 годин помилок вимикають. Події зберігаються й їх можна повторити після ввімкнення.
  • Журнал доставок у кабінеті показує кожну спробу з відповіддю вашого сервера та точним вмістом і дозволяє повторити одну доставку або все пропущене.
  • Відповіді, які ви надсилаєте через API, повертаються як події message.sent з metadata.source = "api" — ігноруйте їх, якщо хочете реагувати лише на чужі повідомлення.
  • Значення url вкладень підписані й діють 6 годин; за свіжим посиланням перечитайте повідомлення.
  • Секрет підпису можна змінити будь-коли. Протягом 24 годин запити підписуються обома, тож перейти можна без простою.

Запитання

  • Чи витрачає надсилання повідомлення через API ліміт ШІ-повідомлень? Ні — це повідомлення в стилі менеджера. Відповіді ШІ клієнтам рахуються як зазвичай.
  • Які тарифи включають API? Наразі Business і Pro; актуальну відповідь завжди показує список тарифів у кабінеті. Якщо ви перейдете на нижчий тариф, ключі й ендпоінти збережуться, але запити відповідатимуть 402, а вебхуки не надсилатимуться — оновіть тариф, щоб повернути їх, і повторіть пропущене з журналу доставок.
  • Чи можуть ключі створювати кілька людей? Ключами та вебхуками керує лише власник акаунта.
  • Чи можна обмежити ключ одним магазином? Так — оберіть проєкти під час створення ключа.
  • Чи є SDK? Поки ні. Документ OpenAPI працює з генераторами, як-от openapi-generator.
  • Щось незрозуміло чи бракує? Пишіть на [email protected].

Усі запити надсилаються на https://marrek.app/api/public/v1