플러그인 만들기

플러그인은 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와 웹훅 비밀 값이 들어 있으며, 비밀 값은 한 번만 표시됩니다. 저장해 두세요. 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": { … }
}

서명, 유효 시간, 논스는 웹훅에서 설명한 그대로 검증하고, 빠르게 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건, 수신 웹훅은 플러그인당 분당 120건으로 제한됩니다.
전송 실패가 계속되면 플러그인이 성능 저하로 표시됩니다. 한 시간 동안 절반 넘게 실패하면 일시 중지되고 계정 관리자에게 알림이 갑니다.
웹훅 비밀 값을 절대 기록하거나 그대로 출력하지 마세요. 노출이 의심되면 교체하세요. 겹치는 기간이 있어 아무것도 깨지지 않습니다.