Plugin készítése

A plugin egy HTTPS-végpont, amely aláírt eseményeket fogad a RolChattől, valamint opcionálisan visszahívja a RolChatet. Nincs feltöltendő kód, és nincs a RolChaten belül futtatandó környezet.

1. A plugin regisztrálása

A Beállítások → Pluginek → Katalógus → Egyéni menüben, vagy az API-val:

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
  }
}

A válasz tartalmazza a plugin azonosítóját és a webhook titkos kulcsát, amely egyszer jelenik meg. Tárold el; a RolChat minden elküldött eseményét ezzel írja alá, és minden eseményt, amelyet te küldesz a RolChatnek, szintén ezzel kell aláírni.

2. Események fogadása a RolChattől

A RolChat változáskor a webhook_url_outbound címre küld:

Esemény	Mikor
chats.conversation.created	Elindul egy beszélgetés
crm.contact.created	Létrejön egy kapcsolat
crm.contact.updated	Egy kapcsolat megváltozik
tickets.ticket.created	Létrejön egy jegy
tickets.ticket.status_changed	Egy jegy állapota változik
marketing.meeting.booked	Megbeszélést foglalnak
marketing.meeting.cancelled	Egy megbeszélést lemondanak

{
  "event": "crm.contact.created",
  "account_id": "…",
  "plugin_id": "…",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": { … }
}

Ellenőrizd az aláírást, a frissességet és a nonce-t pontosan a Webhookok oldalon leírtak szerint, válaszolj gyorsan 200 kóddal, és szűrd a duplikátumokat eseményazonosító alapján. A feliratkozásokhoz elérhető tágabb eseménycsaládok az eseménykatalógusban találhatók.

3. Események küldése a RolChatbe

Küldj a pluginod bejövő végpontjára, ugyanazzal a titkos kulccsal aláírva:

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" }
  }
}

Válasz: { "received": true, "matched_contact_id": "…" }.

Bejövő esemény	Mit csinál a RolChat
contact.data_updated	Eltárolja a plugin_data értéket az egyező kapcsolaton
company.data_updated	Eltárolja a plugin_data értéket az egyező cégen
contact.created_external	Létrehoz vagy frissít egy kapcsolatot
agent.unavailable	Lefuttatja a foglalási űrlap elérhetetlenségi stratégiáját (lemondás, átosztás, új időpont felajánlása)
agent.available	Értesíti az ügynököt a függőben lévő megbeszélésekről

Egyeztetés. A RolChat először e-mail-cím alapján keresi a kapcsolatot, majd a pluginod által korábban eltárolt external_id alapján. Ha nem találja: érdeklődő jön létre, ha a sync_config.create_contacts be van kapcsolva, egyébként az esemény egyeztetetlenként kerül naplózásra.

4. Hol jelennek meg a plugin adatai

A kapcsolat- és cégkártyákon egy, a pluginodról elnevezett szakasz jelenik meg az általad küldött mezőkkel, csak olvasható formában, az utolsó frissítés időpontjával. Ugyanezeket az adatokat az API is visszaadja:

GET /api/v1/contacts/{id}
{
  "data": {
    "id": "…",
    "plugin_data": {
      "{plugin_id}": { "plugin_name": "Acme back office", "updated_at": "…", "data": { … } }
    }
  }
}

Az automatizálási feltételek vizsgálhatják a plugin adatait, így egy szabály az ügyfél rendszeredben szereplő csomagja alapján irányíthat egy beszélgetést.

5. Kezelési 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. Manifest

Egy közzétett plugin egy manifestben írja le önmagát: név, kategória, a kért hatókörök, az események, amelyekre feliratkozik, a beállítási űrlapja, opcionálisan allowed_source_ips, recommended_rotation_days, valamint fizetős plugin esetén az ára. A manifest alapján készül a csatlakozási képernyő, és ez alapján történik az ellenőrzés, mielőtt egy közösségi plugin bekerül a listába.

Korlátok és jó gyakorlatok

• Bejövő törzs legfeljebb 5 MB; kimenő alapértelmezés szerint 1 MB.
• A plugin API-kulcsok percenként 300 kérésre, a bejövő webhookok pluginenként percenként 120-ra korlátozottak.
• A tartós kézbesítési hibák miatt a plugin korlátozott állapotúnak minősül; ha egy órán át a kézbesítések több mint fele sikertelen, a plugin szünetel, és a fiók adminisztrátorai értesítést kapnak.
• Soha ne naplózd és ne írd ki a webhook titkos kulcsát. Cseréld le, ha kiszivárgásra gyanakszol; az átfedési időablaknak köszönhetően semmi sem romlik el.