构建插件

插件是一个接收 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 中的说明验证签名、时效和 nonce，快速返回 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 密钥限制为每分钟 300 次请求；入站 Webhook 每个插件每分钟 120 次。
持续的投递失败会将插件标记为降级；一小时内超过一半失败会暂停插件并通知账户管理员。
绝不要记录或回显 Webhook 密钥。如果怀疑已泄露，请轮换它；有重叠窗口，因此不会造成中断。