Eklenti geliştirme

Bir eklenti, RolChat’ten imzalı olaylar alan bir HTTPS endpoint’i ve isteğe bağlı olarak RolChat’e geri yaptığı çağrılardır. RolChat’e yüklenecek kod veya RolChat içinde barındırılacak bir çalışma ortamı yoktur.

1. Eklentiyi kaydedin

Ayarlar → Eklentiler → Katalog → Özel bölümünden veya API ile:

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

Yanıt, eklenti kimliğini ve bir kez gösterilen webhook gizli anahtarını içerir. Onu saklayın; RolChat’in gönderdiği her olay bununla imzalanır ve sizin RolChat’e gönderdiğiniz her olayın da öyle olması gerekir.

2. RolChat’ten olay alma

Bir şey değiştiğinde RolChat webhook_url_outbound adresine gönderim yapar:

Olay	Ne zaman
chats.conversation.created	Bir konuşma başladığında
crm.contact.created	Bir kişi oluşturulduğunda
crm.contact.updated	Bir kişi değiştiğinde
tickets.ticket.created	Bir destek talebi oluşturulduğunda
tickets.ticket.status_changed	Bir destek talebinin durumu değiştiğinde
marketing.meeting.booked	Bir toplantı rezerve edildiğinde
marketing.meeting.cancelled	Bir toplantı iptal edildiğinde

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

İmzayı, güncelliği ve nonce’u tam olarak Webhook’lar bölümünde açıklandığı gibi doğrulayın, hızla 200 yanıtı verin ve olay kimliğine göre tekilleştirin. Abonelikler için kullanılabilen daha geniş olay aileleri olay kataloğundadır.

3. RolChat’e olay gönderme

Aynı gizli anahtarla imzalayarak eklentinizin gelen endpoint’ine gönderin:

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

Yanıt: { "received": true, "matched_contact_id": "…" }.

Gelen olay	RolChat ne yapar
contact.data_updated	plugin_data değerini eşleşen kişiye kaydeder
company.data_updated	plugin_data değerini eşleşen şirkete kaydeder
contact.created_external	Bir kişi oluşturur veya günceller
agent.unavailable	Rezervasyon formunun müsait olmama stratejisini çalıştırır (iptal, yeniden atama, yeni zaman aralığı önerme)
agent.available	Temsilciyi bekleyen toplantılar hakkında bilgilendirir

Eşleştirme. RolChat kişiyi önce e-postaya, ardından eklentinizin daha önce sakladığı external_id değerine göre arar. Bulunamazsa: sync_config.create_contacts açıksa bir potansiyel müşteri oluşturulur, aksi halde olay eşleşmemiş olarak kaydedilir.

4. Eklenti verileri nerede görünür

Kişi ve şirket kartları, eklentinizin adını taşıyan bir bölümde gönderdiğiniz alanları salt okunur olarak ve son güncelleme zamanıyla birlikte gösterir. Aynı veriler API tarafından da döndürülür:

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

Otomasyon koşulları eklenti verilerini kontrol edebilir; böylece bir kural, bir konuşmayı müşterinin sisteminizdeki planına göre yönlendirebilir.

5. Yönetim 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

Yayınlanan bir eklenti kendini bir manifest dosyasında tanımlar: ad, kategori, istediği kapsamlar, abone olduğu olaylar, ayarlar formu, isteğe bağlı allowed_source_ips, recommended_rotation_days ve ücretliyse fiyatlandırması. Manifest, bağlantı ekranını ve bir topluluk eklentisi listelenmeden önceki incelemeyi yönlendirir.

Sınırlar ve iyi uygulamalar

• Gelen gövde en fazla 5 MB; giden varsayılan olarak 1 MB.
• Eklenti API anahtarları dakikada 300 istekle, gelen webhook’lar eklenti başına dakikada 120 ile sınırlıdır.
• Süregelen teslimat hataları bir eklentiyi bozulmuş olarak işaretler; bir saat boyunca yarıdan fazlası başarısız olursa eklenti duraklatılır ve hesap yöneticileri bilgilendirilir.
• Webhook gizli anahtarını asla loglamayın veya geri yansıtmayın. Açığa çıktığından şüpheleniyorsanız döndürün; örtüşme penceresi sayesinde hiçbir şey bozulmaz.