Plagin yaradın

Plagin RolChat-dən imzalı hadisələr qəbul edən HTTPS endpoint-i, üstəgəl RolChat-ə geri etdiyi istəyə bağlı çağırışlardır. RolChat-ə yüklənəcək kod və ya RolChat daxilində host ediləcək runtime yoxdur.

1. Plagini qeydiyyatdan keçirin

Parametrlər → Plaginlər → Kataloq → Xüsusi bölməsində və ya API ilə:

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
  }
}

Cavab plaginin ID-sini və bir dəfə göstərilən webhook gizli açarını ehtiva edir. Onu saxlayın; RolChat-in göndərdiyi hər hadisə onunla imzalanır və sizin RolChat-ə göndərdiyiniz hər hadisə də belə olmalıdır.

2. RolChat-dən hadisələrin qəbulu

Nəsə dəyişəndə RolChat webhook_url_outbound ünvanına göndərir:

Hadisə	Nə vaxt
chats.conversation.created	Söhbət başlayır
crm.contact.created	Kontakt yaradılır
crm.contact.updated	Kontakt dəyişir
tickets.ticket.created	Tiket yaradılır
tickets.ticket.status_changed	Tiketin statusu dəyişir
marketing.meeting.booked	Görüş bronlanır
marketing.meeting.cancelled	Görüş ləğv edilir

{
  "event": "crm.contact.created",
  "account_id": "…",
  "plugin_id": "…",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": { … }
}

İmzanı, təzəliyi və nonce-u tam olaraq Webhook-lar bölməsində təsvir olunduğu kimi yoxlayın, tez 200 cavabı verin və hadisə ID-si üzrə dublikatları aradan qaldırın. Abunəliklər üçün mövcud olan daha geniş hadisə ailələri hadisələr kataloqundadır.

3. RolChat-ə hadisələrin göndərilməsi

Eyni gizli açarla imzalayaraq plagininizin daxil olan endpoint-inə göndərin:

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" }
  }
}

Cavab: { "received": true, "matched_contact_id": "…" }.

Daxil olan hadisə	RolChat nə edir
contact.data_updated	plugin_data dəyərini uyğun kontaktda saxlayır
company.data_updated	plugin_data dəyərini uyğun şirkətdə saxlayır
contact.created_external	Kontakt yaradır və ya yeniləyir
agent.unavailable	Bron formasının əlçatmazlıq strategiyasını icra edir (ləğv, yenidən təyinat, yeni vaxt təklifi)
agent.available	Operatoru gözləyən görüşlər barədə xəbərdar edir

Uyğunlaşdırma. RolChat kontaktı əvvəlcə e-poçt, sonra plagininizin əvvəllər saxladığı external_id üzrə axtarır. Tapılmasa: sync_config.create_contacts aktivdirsə, lead yaradılır, əks halda hadisə uyğunlaşdırılmamış kimi jurnala yazılır.

4. Plagin məlumatları harada görünür

Kontakt və şirkət kartları plagininizin adını daşıyan bölmədə göndərdiyiniz sahələri yalnız oxumaq üçün, son yeniləmə vaxtı ilə göstərir. Eyni məlumatları API də qaytarır:

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

Avtomatlaşdırma şərtləri plagin məlumatlarını yoxlaya bilər, belə ki, qayda söhbəti müştərinin sizin sisteminizdəki planına görə yönləndirə bilər.

5. İdarəetmə API-si

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. Manifest

Dərc edilmiş plagin özünü manifestdə elan edir: ad, kateqoriya, tələb etdiyi scope-lar, abunə olduğu hadisələr, parametrlər forması, istəyə bağlı allowed_source_ips, recommended_rotation_days və ödənişlidirsə qiyməti. Manifest qoşulma ekranını və icma plagini siyahıya salınmazdan əvvəlki yoxlamanı müəyyən edir.

Limitlər və gigiyena

• Daxil olan gövdə 5 MB-a qədər; gedən standart olaraq 1 MB.
• Plagin API açarları dəqiqədə 300 sorğu ilə, daxil olan webhook-lar isə hər plagin üçün dəqiqədə 120 ilə məhdudlaşır.
• Davamlı çatdırılma uğursuzluqları plagini zəifləmiş kimi işarələyir; bir saat ərzində yarıdan çoxu uğursuz olarsa, plagin dayandırılır və hesab adminlərinə bildiriş göndərilir.
• Webhook gizli açarını heç vaxt loglamayın və geri qaytarmayın. İfşa olunduğundan şübhələnirsinizsə, onu rotasiya edin; üst-üstə düşmə pəncərəsi sayəsində heç nə pozulmur.