Швидкий старт
Потрібен акаунт 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 | Значення |
|---|---|---|
| 401 | invalid_api_key | Ключ відсутній, має неправильний формат або невідомий |
| 401 | api_key_revoked | Ключ відкликано в кабінеті |
| 401 | api_key_expired | Термін дії ключа минув |
| 401 | api_key_disabled | Власник, що створив ключ, більше не має доступу |
| 402 | plan_limit_exceeded (error.limit = api_access) | Тариф акаунта не включає API — перевіряється на кожному запиті |
| 429 | too_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), щоб фільтри за днями та аналітика рахувались за вашу календарну добу; часовий пояс, закріплений у налаштуваннях власника ключа, має пріоритет.
| Статус | Коли |
|---|---|
| 400 | X-Project-Id не є числом (invalid_project_id) |
| 401 / 403 | Див. «Автентифікація» та «Права доступу» |
| 404 | Ресурсу немає в цьому проєкті (або він належить іншому) |
| 409 | project_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 на кожну відповідну подію.
Кожен запит виглядає так:
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
