Плагин жасау

Плагин - RolChat-тан қол қойылған оқиғаларды алатын HTTPS эндпоинті, сондай-ақ оның 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 webhook_url_outbound мекенжайына POST сұрауын жібереді:

Оқиға	Қашан
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-мен шектелген.
• Тұрақты жеткізу ақаулары плагинді нашарлаған деп белгілейді; бір сағат бойы жартысынан көбі сәтсіз болса, ол уақытша тоқтатылып, аккаунт әкімшілеріне хабарланады.
• Вебхук құпиясын ешқашан логқа жазбаңыз және шығармаңыз. Ол әшкере болды деп күдіктенсеңіз, ауыстырыңыз; қабаттасу кезеңінің арқасында ештеңе бұзылмайды.