สร้างปลั๊กอิน

ปลั๊กอินคือเอนด์พอยต์ HTTPS ที่รับเหตุการณ์ที่ลงลายมือชื่อจาก RolChat และอาจเรียกกลับเข้า 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 ส่ง POST ไปที่ 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": { … }
}

ตรวจสอบลายมือชื่อ ความสดใหม่ และ 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 คำขอต่อนาที เว็บฮุกขาเข้า 120 ครั้งต่อนาทีต่อปลั๊กอิน
• การส่งที่ล้มเหลวต่อเนื่องจะทำเครื่องหมายปลั๊กอินว่าเสื่อมประสิทธิภาพ หากล้มเหลวเกินครึ่งนานหนึ่งชั่วโมง ปลั๊กอินจะถูกหยุดชั่วคราวและแจ้งผู้ดูแลระบบของบัญชี
• ห้ามบันทึกหรือแสดงซีเคร็ตเว็บฮุก หมุนเวียนซีเคร็ตหากสงสัยว่ารั่วไหล ช่วงเวลาซ้อนทับทำให้ไม่มีอะไรเสียหาย