प्लगइन बनाएँ

प्लगइन एक 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 webhook_url_outbound पर POST करता है:

इवेंट	कब
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 तक।
• लगातार डिलीवरी विफलताएँ प्लगइन को डिग्रेडेड चिह्नित करती हैं; एक घंटे तक आधे से ज़्यादा विफल होने पर प्लगइन रुक जाता है और खाते के एडमिन को सूचना मिलती है।
• वेबहुक सीक्रेट कभी लॉग या इको न करें। लीक होने का संदेह हो तो उसे रोटेट करें; ओवरलैप विंडो की वजह से कुछ नहीं टूटता।