Ustvarite vtičnik

Vtičnik je končna točka HTTPS, ki prejema podpisane dogodke iz RolChat, in neobvezni klici, ki jih izvaja nazaj v RolChat. Ni kode za nalaganje in ni izvajalnega okolja, ki bi ga gostili v RolChat.

1. Registrirajte vtičnik

V Nastavitve → Vtičniki → Katalog → Po meri ali prek API-ja:

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

Odgovor vsebuje ID vtičnika in skrivnost webhooka, prikazano samo enkrat. Shranite jo; vsak dogodek, ki ga pošlje RolChat, je podpisan z njo, in tako mora biti tudi vsak dogodek, ki ga pošljete v RolChat.

2. Prejemajte dogodke iz RolChat

RolChat pošlje POST na webhook_url_outbound, ko se kaj spremeni:

Dogodek	Kdaj
chats.conversation.created	Začne se pogovor
crm.contact.created	Ustvarjen je stik
crm.contact.updated	Stik se spremeni
tickets.ticket.created	Ustvarjen je zahtevek
tickets.ticket.status_changed	Zahtevek spremeni stanje
marketing.meeting.booked	Rezerviran je sestanek
marketing.meeting.cancelled	Sestanek je odpovedan

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

Preverite podpis, svežino in nonce natanko tako, kot je opisano v razdelku Webhooki, hitro odgovorite z 200 in odstranite dvojnike po ID-ju dogodka. Širše družine dogodkov, ki so na voljo za naročnine, so v katalogu dogodkov.

3. Pošiljajte dogodke v RolChat

Pošljite POST na dohodno končno točko svojega vtičnika, podpisan z isto skrivnostjo:

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

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

Dohodni dogodek	Kaj naredi RolChat
contact.data_updated	Shrani plugin_data pri ujemajočem se stiku
company.data_updated	Shrani plugin_data pri ujemajočem se podjetju
contact.created_external	Ustvari ali posodobi stik
agent.unavailable	Zažene strategijo nedosegljivosti obrazca za rezervacije (odpoved, prerazporeditev, ponudba novega termina)
agent.available	Obvesti agenta o čakajočih sestankih

Ujemanje. RolChat stik najprej poišče po e-poštnem naslovu, nato po external_id, ki ga je vaš vtičnik shranil prej. Ni najdeno: ustvari se potencialna stranka, če je vklopljen sync_config.create_contacts, sicer se dogodek zabeleži kot neujemajoč.

4. Kje se prikažejo podatki vtičnika

Kartice stikov in podjetij prikazujejo razdelek, poimenovan po vašem vtičniku, s poslanimi polji, samo za branje, s časom zadnje posodobitve. Iste podatke vrne tudi API:

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

Pogoji avtomatizacije lahko preverjajo podatke vtičnikov, zato lahko pravilo pogovor usmeri glede na paket stranke v vašem sistemu.

5. API za upravljanje

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

Objavljen vtičnik se opiše v manifestu: ime, kategorija, zahtevani obsegi, dogodki, na katere se naroči, obrazec z nastavitvami, neobvezni allowed_source_ips, recommended_rotation_days in cena, če je plačljiv. Manifest poganja zaslon za povezavo in pregled, preden je vtičnik skupnosti uvrščen v katalog.

Omejitve in dobre prakse

• Dohodno telo do 5 MB; odhodno privzeto 1 MB.
• Ključi API vtičnikov so omejeni na 300 zahtev na minuto; dohodni webhooki na 120 na minuto na vtičnik.
• Trajne napake pri dostavi vtičnik označijo kot okrnjen; če več kot polovica dostav ne uspe eno uro, se vtičnik začasno ustavi, skrbniki računa pa prejmejo obvestilo.
• Skrivnosti webhooka nikoli ne beležite in je ne vračajte. Zamenjajte jo, če sumite, da je razkrita; zaradi obdobja prekrivanja se nič ne pokvari.