Xây dựng plugin

Plugin là một endpoint HTTPS nhận sự kiện có ký từ RolChat, cộng với các lệnh gọi tùy chọn mà nó thực hiện ngược lại vào RolChat. Không có mã nào phải tải lên và không có runtime nào phải lưu trữ bên trong RolChat.

1. Đăng ký plugin

Trong Cài đặt → Plugin → Danh mục → Tùy chỉnh, hoặc qua 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
  }
}

Phản hồi chứa ID của plugin và khóa bí mật webhook, chỉ hiển thị một lần. Hãy lưu lại; mọi sự kiện RolChat gửi đều được ký bằng khóa này, và mọi sự kiện bạn gửi vào RolChat cũng phải như vậy.

2. Nhận sự kiện từ RolChat

RolChat gửi đến webhook_url_outbound khi có thay đổi:

Sự kiện	Khi nào
chats.conversation.created	Một cuộc trò chuyện bắt đầu
crm.contact.created	Một liên hệ được tạo
crm.contact.updated	Một liên hệ thay đổi
tickets.ticket.created	Một ticket được tạo
tickets.ticket.status_changed	Một ticket chuyển trạng thái
marketing.meeting.booked	Một cuộc hẹn được đặt
marketing.meeting.cancelled	Một cuộc hẹn bị hủy

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

Xác minh chữ ký, độ mới và nonce đúng như mô tả trong Webhook, trả về 200 nhanh chóng và loại bỏ trùng lặp theo ID sự kiện. Các nhóm sự kiện rộng hơn dành cho đăng ký có trong danh mục sự kiện.

3. Gửi sự kiện vào RolChat

Gửi đến endpoint nhận của plugin, được ký bằng cùng khóa bí mật:

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

Phản hồi: { "received": true, "matched_contact_id": "…" }.

Sự kiện gửi vào	RolChat làm gì
contact.data_updated	Lưu plugin_data vào liên hệ khớp
company.data_updated	Lưu plugin_data vào công ty khớp
contact.created_external	Tạo hoặc cập nhật một liên hệ
agent.unavailable	Chạy chiến lược xử lý khi vắng mặt của biểu mẫu đặt lịch (hủy, giao lại, đề xuất khung giờ mới)
agent.available	Thông báo cho nhân viên về các cuộc hẹn đang chờ

Đối chiếu. RolChat tìm liên hệ theo email trước, sau đó theo external_id mà plugin của bạn đã lưu trước đó. Không tìm thấy: một khách hàng tiềm năng được tạo nếu sync_config.create_contacts được bật, nếu không sự kiện được ghi nhật ký là không khớp.

4. Dữ liệu plugin hiển thị ở đâu

Thẻ liên hệ và công ty hiển thị một mục mang tên plugin của bạn với các trường bạn đã gửi, ở chế độ chỉ đọc, kèm thời điểm cập nhật gần nhất. API cũng trả về cùng dữ liệu đó:

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

Điều kiện tự động hóa có thể kiểm tra dữ liệu plugin, nên một quy tắc có thể định tuyến cuộc trò chuyện theo gói của khách hàng trong hệ thống của bạn.

5. API quản lý

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

Plugin đã xuất bản tự khai báo trong manifest: tên, loại, các scope yêu cầu, các sự kiện đăng ký, biểu mẫu cài đặt, allowed_source_ips tùy chọn, recommended_rotation_days và giá nếu có trả phí. Manifest điều khiển màn hình kết nối và bước duyệt trước khi một plugin cộng đồng được niêm yết.

Giới hạn và vệ sinh bảo mật

• Body gửi vào tối đa 5 MB; body gửi đi mặc định 1 MB.
• Khóa API plugin bị giới hạn 300 yêu cầu mỗi phút; webhook gửi vào bị giới hạn 120 mỗi phút cho mỗi plugin.
• Lỗi gửi kéo dài sẽ đánh dấu plugin là suy giảm; nếu hơn một nửa số lần gửi thất bại trong một giờ, plugin bị tạm dừng và admin tài khoản được thông báo.
• Không bao giờ ghi log hoặc hiển thị lại khóa bí mật webhook. Hãy xoay vòng nếu nghi ngờ bị lộ; nhờ cửa sổ chồng lấp, không có gì bị hỏng.