Sukurkite įskiepį

Įskiepis yra HTTPS galinis taškas, gaunantis pasirašytus RolChat įvykius, ir neprivalomi iškvietimai, kuriuos jis atlieka atgal į RolChat. Nereikia įkelti jokio kodo ir talpinti jokios vykdymo aplinkos RolChat viduje.

1. Užregistruokite įskiepį

Skiltyje Nustatymai → Įskiepiai → Katalogas → Pasirinktinis arba per 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
  }
}

Atsakyme yra įskiepio ID ir webhook’o paslaptis, parodoma vieną kartą. Išsaugokite ją; kiekvienas RolChat siunčiamas įvykis pasirašomas ja, ir kiekvienas jūsų į RolChat siunčiamas įvykis taip pat turi būti ja pasirašytas.

2. Gaukite įvykius iš RolChat

RolChat siunčia į webhook_url_outbound, kai kas nors pasikeičia:

Įvykis	Kada
chats.conversation.created	Prasideda pokalbis
crm.contact.created	Sukuriamas kontaktas
crm.contact.updated	Pasikeičia kontaktas
tickets.ticket.created	Sukuriama užklausa
tickets.ticket.status_changed	Užklausa pereina į kitą būseną
marketing.meeting.booked	Rezervuojamas susitikimas
marketing.meeting.cancelled	Atšaukiamas susitikimas

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

Patikrinkite parašą, šviežumą ir nonce tiksliai taip, kaip aprašyta puslapyje Webhook’ai, greitai atsakykite 200 ir šalinkite dublikatus pagal įvykio ID. Platesnės prenumeratoms prieinamos įvykių šeimos pateiktos įvykių kataloge.

3. Siųskite įvykius į RolChat

Siųskite į savo įskiepio gaunamų įvykių galinį tašką, pasirašę ta pačia paslaptimi:

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

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

Gaunamas įvykis	Ką daro RolChat
contact.data_updated	Išsaugo plugin_data atitinkamame kontakte
company.data_updated	Išsaugo plugin_data atitinkamoje įmonėje
contact.created_external	Sukuria arba atnaujina kontaktą
agent.unavailable	Vykdo rezervavimo formos nepasiekiamumo strategiją (atšaukti, perskirti, pasiūlyti naują laiką)
agent.available	Praneša agentui apie laukiančius susitikimus

Susiejimas. RolChat pirmiausia ieško kontakto pagal el. paštą, tada pagal external_id, kurį jūsų įskiepis išsaugojo anksčiau. Nerastas: sukuriamas potencialus klientas, jei įjungtas sync_config.create_contacts, kitaip įvykis registruojamas kaip nesusietas.

4. Kur rodomi įskiepio duomenys

Kontaktų ir įmonių kortelėse rodoma jūsų įskiepio pavadinimu pavadinta skiltis su jūsų atsiųstais laukais, tik skaitymui, su paskutinio atnaujinimo laiku. Tuos pačius duomenis grąžina ir API:

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

Automatizavimo sąlygos gali tikrinti įskiepio duomenis, todėl taisyklė gali nukreipti pokalbį pagal kliento planą jūsų sistemoje.

5. Valdymo 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. Manifestas

Paskelbtas įskiepis save aprašo manifeste: pavadinimas, kategorija, prašomos aprėptys, prenumeruojami įvykiai, nustatymų forma, neprivalomi allowed_source_ips, recommended_rotation_days ir kaina, jei jis mokamas. Manifestas valdo prijungimo ekraną ir peržiūrą prieš įtraukiant bendruomenės įskiepį į katalogą.

Limitai ir higiena

• Gaunamas turinys iki 5 MB; siunčiamas numatytai 1 MB.
• Įskiepių API raktai ribojami iki 300 užklausų per minutę; gaunami webhook’ai iki 120 per minutę vienam įskiepiui.
• Ilgai trunkantys pristatymo sutrikimai pažymi įskiepį kaip veikiantį su trikdžiais; jei valandą nepavyksta daugiau nei pusė pristatymų, jis pristabdomas ir apie tai pranešama paskyros administratoriams.
• Niekada neregistruokite ir neišveskite webhook’o paslapties. Jei įtariate, kad ji atskleista, pakeiskite ją; dėl persidengimo lango niekas nesugenda.