Скринька і Supporter

Скринька — спільна для команди стрічка розмов із клієнтами з месенджерів і соцмереж. Самі підключення до Telegram, Instagram, Viber, WhatsApp і Facebook тримає Supporter — окремий сервіс, який пересилає повідомлення клієнтів у Systemer і забирає відповіді агентів назад. Systemer із месенджерами напряму не говорить.

Кожна розмова — бесіда в «Клієнти → Скринька»: видно канал, імʼя співрозмовника, хто з команди відповідає і чи чекає клієнт на відповідь. Бесіду можна звʼязати з лідом або контрагентом — і листування стає частиною історії клієнта, а не лишається в чиємусь телефоні.

Скринька спільна: її бачить кожен, хто має дозвіл «Доступ до скриньки», без запрошення в конкретну бесіду. Призначення агента — лише спосіб домовитись, хто відповідає, а не межа доступу. Це навмисно інакше, ніж у внутрішніх чатах, де бесіду бачать лише учасники.

• Налаштування → Скринька → «Підключити Supporter». Створюється конектор і два секрети: ключ, яким Supporter надсилає події нам, і секрет, яким ми підписуємо відповіді. Обидва показуються один раз.
• Адресу для Supporter (POST /api/webhooks/supporter/<id>) і ключ вставте в налаштування Supporter.
• Адресу Supporter для відповідей і секрет підпису задайте в конекторі. Поки адреси немає, повідомлення клієнтів приймаються, а відповіді агентів чекають у черзі.
• Оберіть, кому призначати нові бесіди: ця людина отримує сповіщення про кожне повідомлення клієнта, доки бесіду не передали іншому.

Supporter надсилає POST на адресу конектора з ключем у заголовку Systemer-Key. Заголовок Systemer-Idempotency-Key необовʼязковий: без нього ключем повтору стає хеш тіла. Тіло — одна з чотирьох подій, поле type каже яка.

POST /api/webhooks/supporter/<connector_id>
Systemer-Key: inbk_…
Content-Type: application/json

{
  "type": "message.received",
  "conversation": {
    "ref": "tg:123456789",
    "channel": "telegram",
    "peer": { "ref": "tg-user:987", "name": "Олена Петренко", "handle": "@olena" }
  },
  "message": {
    "ref": "tg-msg:42",
    "text": "Добрий день! Хочу дізнатись про вартість аудиту.",
    "sent_at": "2026-10-04T09:15:00+03:00",
    "attachments": [{ "url": "https://…/photo.jpg", "filename": "photo.jpg", "mime_type": "image/jpeg" }]
  }
}

Агент відповідає або в Systemer, або в самому Supporter — і розмова має виглядати однаково в обох випадках. Тому подій про повідомлення дві: message.received несе слова клієнта, message.sent — відповідь, набрану в Supporter. Надсилати друге під виглядом першого не можна: у Скриньці відповідь менеджера стала б словами клієнта, під його імʼям, а бесіда позначилась би як така, що чекає на відповідь, хоча її вже дали.

{
  "type": "message.sent",
  "conversation": {
    "ref": "telegram:conv:8c7d6e5f-…",
    "channel": "telegram",
    "peer": { "ref": "telegram:user:0f1a…", "name": "Олена Петренко" }
  },
  "message": {
    "ref": "telegram:msg:aaaaaaaa-…",
    "text": "Дякуємо! Надішлю розрахунок сьогодні до вечора.",
    "sent_at": "2026-10-04T09:20:00+03:00",
    "reply_to_ref": "telegram:msg:bbbbbbbb-…",
    "attachments": []
  },
  "sender": { "name": "Анна Ковальчук" }
}

• conversation.ref — ідентифікатор треду в Supporter. Повторне повідомлення з тим самим ref лягає в наявну бесіду. channel — один із: telegram, instagram, facebook, viber, whatsapp, email, web, other.
• message.ref — ідентифікатор повідомлення в Supporter. Повтор із тим самим ref не створює дубля. Текст або вкладення — принаймні щось одне; вкладення лишаються за посиланням у Supporter.
• message.sent — відповідь агента, набрана в Supporter. Лягає на бік менеджера, поруч із відповідями з CRM, і знімає з бесіди позначку «чекає на відповідь». sender.name показується як автор; без нього автор підписується «Інтеграція».
• Стан такої відповіді за замовчуванням — «Надіслано», а не «Доставлено»: «пішло клієнту» і «месенджер підтвердив» — різні факти. Знаєте більше — передайте "status": "delivered"; дізнаєтесь пізніше — надішліть message.status.
• message.status — стан доставки нашої відповіді: { "type": "message.status", "message_id": "<id з конверта message.send>", "status": "delivered" }. Стани: sent, delivered, read, failed (з полем error).
• conversation.updated — змінились імʼя, нік або аватар співрозмовника; тіло — те саме поле conversation.
• Відповідь 201 із conversation_id і message_id; повтор — 200 з duplicate: true і тим самим результатом; помилка в тілі — 422 з поясненням.
• Увага на одну літеру: message.send — це тип НАШОГО конверта до Supporter, message.sent — подія Supporter до нас. Напрямки протилежні.

Відповідь агента їде POST-ом на адресу конектора одразу після надсилання; те, що не доїхало, добирає повторна доставка за розкладом 10 с, 30 с, 2 хв, 10 хв, 1 год, 6 год. Підпис — той самий, що у вихідних вебхуків: заголовок Systemer-Signature з t=<unix> і v1=<HMAC-SHA256 від "<t>.<тіло>">, секрет — із конектора.

POST <адреса Supporter>
Systemer-Signature: t=1791234567,v1=5257a869…
Systemer-Event-Type: message.send
Content-Type: application/json

{
  "id": "0f1a…",
  "type": "message.send",
  "created_at": "2026-10-04T09:20:00.000Z",
  "conversation": { "id": "…", "ref": "tg:123456789", "channel": "telegram", "peer_ref": "tg-user:987" },
  "message": { "id": "0f1a…", "text": "Дякуємо! Надішлю розрахунок сьогодні.", "sent_at": "…", "reply_to_ref": null, "attachments": [] },
  "sender": { "name": "Анна Ковальчук" }
}

• Supporter відповідає 2xx, коли прийняв повідомлення в роботу. У тілі може повернути ref (ідентифікатор у месенджері) і status (sent, delivered або read), якщо знає його одразу.
• Далі про стан доставки Supporter повідомляє подією message.status за message.id з конверта. Агент бачить стан під своїм повідомленням: у черзі, надіслано, доставлено, прочитано, не доставлено.
• Вкладення у відповідях агентів поки не надсилаються — композер скриньки приймає лише текст.