בניית תוסף

תוסף הוא נקודת קצה 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
  }
}

התגובה מכילה את מזהה התוסף ואת סוד ה-webhook, שמוצג פעם אחת. שמרו אותו; כל אירוע ש-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 בדיוק כמתואר ב-Webhooks, ענו 200 מהר, והסירו כפילויות לפי מזהה האירוע. משפחות האירועים הרחבות יותר שזמינות למינויים נמצאות בקטלוג האירועים.

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 בקשות לדקה; webhooks נכנסים ל-120 לדקה לכל תוסף.
• כשלי משלוח מתמשכים מסמנים תוסף כפגוע; יותר ממחצית כושלים במשך שעה משהים אותו ומודיעים למנהלי החשבון.
• לעולם אל תרשמו ביומן ואל תחזירו את סוד ה-webhook. החליפו אותו אם אתם חושדים בחשיפה; חלון החפיפה אומר ששום דבר לא יישבר.