Loo pistikprogramm

Pistikprogramm on HTTPS-lõpp-punkt, mis võtab RolChatilt vastu allkirjastatud sündmusi, pluss valikulised väljakutsed, mida see RolChati tagasi teeb. Pole koodi, mida üles laadida, ega käituskeskkonda, mida RolChati sees majutada.

1. Registreeri pistikprogramm

Jaotises Seaded → Pistikprogrammid → Kataloog → Kohandatud või API kaudu:

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

Vastus sisaldab pistikprogrammi ID-d ja veebihaagi saladust, mida näidatakse üks kord. Salvesta see; iga RolChati saadetud sündmus on sellega allkirjastatud ja iga sündmus, mille sina RolChatile saadad, peab samuti olema.

2. Võta RolChatilt sündmusi vastu

RolChat postitab muudatuste korral aadressile webhook_url_outbound:

Sündmus	Millal
chats.conversation.created	Vestlus algab
crm.contact.created	Kontakt luuakse
crm.contact.updated	Kontakt muutub
tickets.ticket.created	Pilet luuakse
tickets.ticket.status_changed	Pileti olek muutub
marketing.meeting.booked	Kohtumine broneeritakse
marketing.meeting.cancelled	Kohtumine tühistatakse

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

Kontrolli allkirja, värskust ja nonce’i täpselt nii, nagu kirjeldab Veebihaagid, vasta kiiresti 200 ja eemalda duplikaadid sündmuse ID järgi. Tellimustele saadaolevad laiemad sündmuste perekonnad on sündmuste kataloogis.

3. Saada sündmusi RolChati

Postita oma pistikprogrammi sissetulevasse lõpp-punkti, allkirjastatuna sama saladusega:

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

Vastus: { "received": true, "matched_contact_id": "…" }.

Sissetulev sündmus	Mida RolChat teeb
contact.data_updated	Salvestab plugin_data sobivale kontaktile
company.data_updated	Salvestab plugin_data sobivale ettevõttele
contact.created_external	Loob või uuendab kontakti
agent.unavailable	Käivitab broneerimisvormi kättesaamatuse strateegia (tühista, määra ümber, paku uut aega)
agent.available	Teavitab agenti ootel kohtumistest

Sobitamine. RolChat otsib kontakti esmalt e-posti järgi, seejärel external_id järgi, mille sinu pistikprogramm varem salvestas. Ei leitud: müügivihje luuakse, kui sync_config.create_contacts on sees, muidu logitakse sündmus sobitamatuna.

4. Kus pistikprogrammi andmed ilmuvad

Kontakti- ja ettevõttekaardid näitavad sinu pistikprogrammi järgi nimetatud jaotist sinu saadetud väljadega, ainult lugemiseks, koos viimase uuenduse ajaga. Samu andmeid tagastab API:

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

Automatiseerimise tingimused saavad pistikprogrammi andmeid kontrollida, nii et reegel saab suunata vestlust kliendi paketi järgi sinu süsteemis.

5. Haldus-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

Avaldatud pistikprogramm kirjeldab end manifestis: nimi, kategooria, küsitavad ulatused, tellitavad sündmused, seadete vorm, valikulised allowed_source_ips, recommended_rotation_days ja tasulise pistikprogrammi puhul hind. Manifest juhib ühendamise ekraani ja ülevaatust enne kogukonna pistikprogrammi loendisse lisamist.

Piirangud ja hügieen

• Sissetuleva sisu maht kuni 5 MB; väljamineva vaikimisi 1 MB.
• Pistikprogrammi API-võtmed on piiratud 300 päringuga minutis; sissetulevad veebihaagid 120-ga minutis pistikprogrammi kohta.
• Püsivad edastustõrked märgivad pistikprogrammi häirituks; kui tunni jooksul ebaõnnestub üle poole, peatatakse see ja teavitatakse konto administraatoreid.
• Ära kunagi logi ega kuva veebihaagi saladust. Vaheta see, kui kahtlustad lekkimist; kattuvusaken tähendab, et midagi ei lähe katki.