Перейти до вмісту

Створення плагіна

Плагін - це HTTPS-ендпоінт, який отримує підписані події від RolChat, плюс необов’язкові виклики, які він сам робить у RolChat. Не потрібно завантажувати код і не потрібно розміщувати середовище виконання всередині RolChat.

1. Зареєструйте плагін

Section titled “1. Зареєструйте плагін”

У розділі Налаштування → Плагіни → Каталог → Власний або через API:

POST /api/v1/plugins
Authorization: Bearer rcp_…
X-Account-Id: <account uuid>


{
  "plugin_type": "custom",
  "name": "Acme back office",
  "api_key_external": "<key RolChat should use to call you, optional>",
  "webhook_url_outbound": "https://backoffice.acme.com/rolchat",
  "sync_config": {
    "enrich_contacts": true,
    "enrich_companies": true,
    "sync_agent_schedule": false,
    "create_contacts": false
  }
}

Відповідь містить ID плагіна і секрет вебхука, який показується один раз. Збережіть його: кожна подія, яку надсилає RolChat, підписана ним, і кожна подія, яку ви надсилаєте в RolChat, теж має бути ним підписана.

2. Отримуйте події від RolChat

Section titled “2. Отримуйте події від RolChat”

RolChat надсилає POST-запит на webhook_url_outbound, коли щось змінюється:

Подія Коли
chats.conversation.created Починається діалог
crm.contact.created Створено контакт
crm.contact.updated Контакт змінився
tickets.ticket.created Створено тікет
tickets.ticket.status_changed Тікет змінив статус
marketing.meeting.booked Заброньовано зустріч
marketing.meeting.cancelled Зустріч скасовано 
{
  "event": "crm.contact.created",
  "account_id": "…",
  "plugin_id": "…",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": { … }
}

Перевіряйте підпис, свіжість і nonce точно так, як описано в розділі Вебхуки, швидко відповідайте 200 і усувайте дублікати за ID події. Ширші сімейства подій, доступні для підписок, перелічено в каталозі подій.

3. Надсилайте події в RolChat

Section titled “3. Надсилайте події в RolChat”

Надсилайте POST-запити на вхідний ендпоінт свого плагіна, підписані тим самим секретом:

POST /api/v1/webhooks/plugin/{plugin_id}
Content-Type: application/json
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=…
X-RolChat-Nonce: nonce_01HK…


{
  "event": "contact.data_updated",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": {
    "external_id": "acme_user_123",
    "email": "user@company.com",
    "plugin_data": { "role": "Admin", "registered_at": "2024-03-15", "last_login": "2026-04-11" }
  }
}

Відповідь: { "received": true, "matched_contact_id": "…" }.

Вхідна подія Що робить RolChat
contact.data_updated Зберігає plugin_data у знайденого контакту
company.data_updated Зберігає plugin_data у знайденої компанії
contact.created_external Створює або оновлює контакт
agent.unavailable Запускає стратегію недоступності форми бронювання (скасування, перепризначення, пропозиція нового слота)
agent.available Сповіщає агента про заплановані зустрічі

Зіставлення. RolChat шукає контакт спочатку за e-mail, потім за external_id, який ваш плагін зберіг раніше. Якщо контакт не знайдено, створюється лід, коли ввімкнено sync_config.create_contacts; інакше подію записують у журнал як незіставлену.

4. Де відображаються дані плагіна

Section titled “4. Де відображаються дані плагіна”

Картки контактів і компаній показують розділ із назвою вашого плагіна та надісланими полями - лише для читання, з часом останнього оновлення. Ті самі дані повертає API:

GET /api/v1/contacts/{id}
{
  "data": {
    "id": "…",
    "plugin_data": {
      "{plugin_id}": { "plugin_name": "Acme back office", "updated_at": "…", "data": { … } }
    }
  }
}

Умови автоматизації можуть перевіряти дані плагіна, тож правило може маршрутизувати діалог, наприклад, за планом клієнта у вашій системі.

5. API керування

Section titled “5. API керування”
GET    /api/v1/plugins                      connected plugins
GET    /api/v1/plugins/catalog              catalogue
POST   /api/v1/plugins                      connect
GET    /api/v1/plugins/{id}                 details
PATCH  /api/v1/plugins/{id}                 settings
DELETE /api/v1/plugins/{id}                 remove
POST   /api/v1/plugins/{id}/activate        activate
POST   /api/v1/plugins/{id}/deactivate      pause
POST   /api/v1/plugins/{id}/test            test the external key
POST   /api/v1/plugins/{id}/webhook-secret/rotate    rotate with a 7-day overlap
POST   /api/v1/plugins/{id}/webhook-secret/revoke    revoke immediately
GET    /api/v1/plugins/{id}/events          event log (direction, status, type, dates, cursor)
GET    /api/v1/plugins/{id}/sync-schedule   schedule and last run
PATCH  /api/v1/plugins/{id}/sync-schedule   { enabled, cron, timezone }
POST   /api/v1/plugins/{id}/sync-schedule/trigger    run now (one per 5 minutes)

6. Маніфест

Section titled “6. Маніфест”

Опублікований плагін описує себе в маніфесті: назва, категорія, запитувані області доступу, події, на які він підписаний, форма налаштувань, необов’язкові allowed_source_ips і recommended_rotation_days, а також ціна, якщо він платний. Маніфест керує екраном підключення та перевіркою перед тим, як плагін спільноти з’явиться в каталозі.

Ліміти й правила гігієни

Section titled “Ліміти й правила гігієни”
  • Вхідне тіло - до 5 MB; вихідне - за замовчуванням 1 MB.
  • API-ключі плагінів обмежено 300 запитами на хвилину; вхідні вебхуки - 120 на хвилину на плагін.
  • Стійкі збої доставки позначають плагін як такий, що працює з перебоями; якщо за годину не проходить понад половина доставок, плагін призупиняється, а адміністратори акаунта отримують сповіщення.
  • Ніколи не записуйте секрет вебхука в логи й не виводьте його. Змініть його, якщо підозрюєте витік; завдяки періоду перекриття нічого не зламається.