Создание плагина

Плагин - это HTTPS-эндпоинт, который получает подписанные события от RolChat, плюс необязательные вызовы, которые он сам делает в RolChat. Не нужно загружать код и не нужно размещать среду выполнения внутри RolChat.

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

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

Отправляйте 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. Где отображаются данные плагина

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

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

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

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. Манифест

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

Лимиты и правила гигиены

• Входящее тело - до 5 MB; исходящее - по умолчанию 1 MB.
• API-ключи плагинов ограничены 300 запросами в минуту; входящие вебхуки - 120 в минуту на плагин.
• Устойчивые сбои доставки помечают плагин как работающий с перебоями; если за час не проходит больше половины доставок, плагин приостанавливается, а администраторы аккаунта получают уведомление.
• Никогда не записывайте секрет вебхука в логи и не выводите его. Смените его, если подозреваете утечку; благодаря периоду перекрытия ничего не сломается.