Preskočiť na obsah

Vytvorte plugin

Plugin je endpoint HTTPS, ktorý prijíma podpísané udalosti z RolChat, plus voliteľné volania, ktoré vykonáva späť do RolChat. Nenahrávate žiadny kód a vnútri RolChat nič nehostujete.

1. Zaregistrujte plugin

Section titled “1. Zaregistrujte plugin”

V Nastavenia → Pluginy → Katalóg → Vlastný, alebo cez 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
  }
}

Odpoveď obsahuje ID pluginu a tajný kľúč webhooku, zobrazený iba raz. Uložte si ho; každá udalosť, ktorú RolChat pošle, je ním podpísaná a každá udalosť, ktorú pošlete do RolChat, musí byť tiež.

2. Prijímajte udalosti z RolChat

Section titled “2. Prijímajte udalosti z RolChat”

RolChat posiela POST na webhook_url_outbound, keď sa niečo zmení:

Udalosť Kedy
chats.conversation.created Začne sa konverzácia
crm.contact.created Vytvorí sa kontakt
crm.contact.updated Kontakt sa zmení
tickets.ticket.created Vytvorí sa tiket
tickets.ticket.status_changed Tiket zmení stav
marketing.meeting.booked Zarezervuje sa stretnutie
marketing.meeting.cancelled Stretnutie sa zruší 
{
  "event": "crm.contact.created",
  "account_id": "…",
  "plugin_id": "…",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": { … }
}

Overte podpis, čerstvosť a nonce presne podľa opisu vo Webhookoch, rýchlo odpovedzte 200 a deduplikujte podľa ID udalosti. Širšie rodiny udalostí dostupné pre odbery nájdete v katalógu udalostí.

3. Posielajte udalosti do RolChat

Section titled “3. Posielajte udalosti do RolChat”

Posielajte POST na prichádzajúci endpoint svojho pluginu, podpísaný tým istým tajným kľúčom:

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

Odpoveď: { "received": true, "matched_contact_id": "…" }.

Prichádzajúca udalosť Čo RolChat urobí
contact.data_updated Uloží plugin_data k zodpovedajúcemu kontaktu
company.data_updated Uloží plugin_data k zodpovedajúcej firme
contact.created_external Vytvorí alebo aktualizuje kontakt
agent.unavailable Spustí stratégiu nedostupnosti rezervačného formulára (zrušenie, prerozdelenie, ponuka nového termínu)
agent.available Upozorní agenta na čakajúce stretnutia

Párovanie. RolChat hľadá kontakt najprv podľa e-mailu, potom podľa external_id, ktoré váš plugin predtým uložil. Nenájdený: ak je zapnuté sync_config.create_contacts, vytvorí sa lead, inak sa udalosť zaloguje ako nespárovaná.

4. Kde sa dáta pluginu zobrazujú

Section titled “4. Kde sa dáta pluginu zobrazujú”

Karty kontaktov a firiem ukazujú sekciu pomenovanú podľa vášho pluginu s poliami, ktoré ste poslali, iba na čítanie a s časom poslednej aktualizácie. Rovnaké dáta vracia aj API:

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

Podmienky automatizácie môžu testovať dáta pluginov, takže pravidlo môže smerovať konverzáciu podľa plánu zákazníka vo vašom systéme.

5. API na správu

Section titled “5. API na správu”
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

Section titled “6. Manifest”

Zverejnený plugin sa opisuje v manifeste: názov, kategória, požadované rozsahy, odoberané udalosti, formulár nastavení, voliteľne allowed_source_ips, recommended_rotation_days a cenník, ak je platený. Manifest riadi obrazovku pripojenia a kontrolu pred zaradením komunitného pluginu do katalógu.

Limity a osvedčené postupy

Section titled “Limity a osvedčené postupy”
  • Prichádzajúce telo najviac 5 MB; odchádzajúce predvolene 1 MB.
  • Kľúče API pluginov sú obmedzené na 300 požiadaviek za minútu; prichádzajúce webhooky na 120 za minútu na plugin.
  • Trvalé zlyhania doručenia označia plugin ako degradovaný; ak viac ako polovica doručení zlyháva počas hodiny, plugin sa pozastaví a administrátori účtu dostanú upozornenie.
  • Tajný kľúč webhooku nikdy nelogujte ani nevracajte v odpovediach. Pri podozrení na únik ho vymeňte; vďaka prekryvnému obdobiu sa nič nepokazí.