プラグインを作る

プラグインとは、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 と Webhook シークレットが含まれ、シークレットは一度だけ表示されます。保存しておいてください。RolChat が送信するすべてのイベントはこのシークレットで署名され、あなたが RolChat に送信するすべてのイベントも同様に署名する必要があります。

2. RolChat からイベントを受信する

変更があると、RolChat は webhook_url_outbound に送信します。

イベント	タイミング
`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": { … }
}

署名、有効期間、ノンスは Webhook の説明どおりに検証し、すぐに 200 を返し、イベント ID で重複を排除してください。購読できるより広範なイベントファミリーはイベントカタログにあります。

3. RolChat にイベントを送信する

同じシークレットで署名して、プラグインの受信エンドポイントに送信します。

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 キーは1分あたり300リクエスト、受信 Webhook はプラグインごとに1分あたり120件に制限されます。
配信の失敗が続くと、プラグインは低下状態としてマークされます。1時間にわたって半数以上が失敗すると一時停止され、アカウントの管理者に通知されます。
Webhook シークレットをログに記録したり、そのまま返したりしないでください。漏洩の疑いがある場合はローテーションしてください。重複期間があるため、何も壊れません。