Lewati ke konten

Membuat plugin

Plugin adalah endpoint HTTPS yang menerima event bertanda tangan dari RolChat, ditambah panggilan opsional yang dilakukannya kembali ke RolChat. Tidak ada kode yang perlu diunggah dan tidak ada runtime yang perlu di-host di dalam RolChat.

1. Daftarkan plugin

Section titled “1. Daftarkan plugin”

Di Pengaturan → Plugin → Katalog → Kustom, atau dengan 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
  }
}

Respons berisi ID plugin dan secret webhook, yang ditampilkan sekali. Simpan secret tersebut; setiap event yang dikirim RolChat ditandatangani dengannya, dan setiap event yang Anda kirim ke RolChat juga harus demikian.

2. Menerima event dari RolChat

Section titled “2. Menerima event dari RolChat”

RolChat mengirim ke webhook_url_outbound saat ada perubahan:

Event Kapan
chats.conversation.created Percakapan dimulai
crm.contact.created Kontak dibuat
crm.contact.updated Kontak berubah
tickets.ticket.created Tiket dibuat
tickets.ticket.status_changed Status tiket berubah
marketing.meeting.booked Pertemuan dipesan
marketing.meeting.cancelled Pertemuan dibatalkan 
{
  "event": "crm.contact.created",
  "account_id": "…",
  "plugin_id": "…",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": { … }
}

Verifikasi tanda tangan, kesegaran, dan nonce persis seperti dijelaskan di Webhook, jawab 200 dengan cepat, dan lakukan deduplikasi berdasarkan ID event. Keluarga event yang lebih luas untuk langganan ada di katalog event.

3. Mengirim event ke RolChat

Section titled “3. Mengirim event ke RolChat”

Kirim ke endpoint masuk plugin Anda, ditandatangani dengan secret yang sama:

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

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

Event masuk Yang dilakukan RolChat
contact.data_updated Menyimpan plugin_data pada kontak yang cocok
company.data_updated Menyimpan plugin_data pada perusahaan yang cocok
contact.created_external Membuat atau memperbarui kontak
agent.unavailable Menjalankan strategi ketidaktersediaan formulir pemesanan (batalkan, alihkan, tawarkan slot baru)
agent.available Memberi tahu agen tentang pertemuan yang tertunda

Pencocokan. RolChat mencari kontak berdasarkan email terlebih dahulu, lalu berdasarkan external_id yang sebelumnya disimpan plugin Anda. Tidak ditemukan: prospek dibuat jika sync_config.create_contacts aktif; jika tidak, event dicatat sebagai tidak cocok.

4. Tempat data plugin muncul

Section titled “4. Tempat data plugin muncul”

Kartu kontak dan perusahaan menampilkan bagian bernama sesuai plugin Anda dengan field yang Anda kirim, hanya baca, beserta waktu pembaruan terakhir. Data yang sama dikembalikan oleh API:

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

Kondisi otomatisasi dapat menguji data plugin, sehingga aturan dapat merutekan percakapan berdasarkan paket pelanggan di sistem Anda.

5. API manajemen

Section titled “5. API manajemen”
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

Section titled “6. Manifest”

Plugin yang diterbitkan mendeklarasikan dirinya dalam manifest: nama, kategori, scope yang diminta, event yang dilanggan, formulir pengaturan, allowed_source_ips opsional, recommended_rotation_days, dan harganya jika berbayar. Manifest mengatur layar koneksi dan tinjauan sebelum plugin komunitas dicantumkan.

Batas dan kebersihan

Section titled “Batas dan kebersihan”
  • Body masuk hingga 5 MB; body keluar default 1 MB.
  • Kunci API plugin dibatasi 300 permintaan per menit; webhook masuk 120 per menit per plugin.
  • Kegagalan pengiriman yang berkelanjutan menandai plugin sebagai terdegradasi; jika lebih dari separuhnya gagal selama satu jam, plugin dijeda dan admin akun diberi tahu.
  • Jangan pernah mencatat atau menampilkan ulang secret webhook. Rotasi jika Anda mencurigai secret bocor; berkat jendela tumpang tindih, tidak ada yang rusak.