Изработка на плагин

Плагинот е 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 го бара контактот прво според е-пошта, потоа според 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 во минута по плагин.
Долготрајните неуспешни испораки го означуваат плагинот како деградиран; ако повеќе од половината не успеат еден час, тој се паузира и администраторите на сметката се известуваат.
Никогаш не ја запишувајте во логот и не ја прикажувајте тајната за вебхук. Ротирајте ја ако се сомневате дека е изложена; периодот на преклопување значи дека ништо нема да се скрши.