Izradite dodatak

Dodatak je HTTPS krajnja točka koja prima potpisane događaje iz RolChata, uz neobavezne pozive koje upućuje natrag u RolChat. Nema koda za prijenos ni okruženja koje treba hostirati unutar RolChata.

1. Registrirajte dodatak

U Postavke → Dodaci → Katalog → Prilagođeni ili putem 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 sadrži ID dodatka i tajnu webhooka, prikazanu samo jednom. Spremite je; svaki događaj koji RolChat pošalje potpisan je njome, a mora biti i svaki događaj koji vi šaljete u RolChat.

2. Primajte događaje iz RolChata

RolChat šalje POST na webhook_url_outbound kada se nešto promijeni:

Događaj	Kada
chats.conversation.created	Započinje razgovor
crm.contact.created	Izrađen je kontakt
crm.contact.updated	Kontakt se promijeni
tickets.ticket.created	Izrađen je tiket
tickets.ticket.status_changed	Tiket promijeni status
marketing.meeting.booked	Rezerviran je sastanak
marketing.meeting.cancelled	Sastanak je otkazan

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

Provjerite potpis, svježinu i nonce točno kako je opisano u Webhookovima, brzo odgovorite s 200 i deduplicirajte po ID-u događaja. Šire obitelji događaja dostupne za pretplate nalaze se u katalogu događaja.

3. Šaljite događaje u RolChat

Šaljite POST na dolaznu krajnju točku svog dodatka, potpisan istom tajnom:

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": "…" }.

Dolazni događaj	Što RolChat radi
contact.data_updated	Pohranjuje plugin_data uz odgovarajući kontakt
company.data_updated	Pohranjuje plugin_data uz odgovarajuću tvrtku
contact.created_external	Izrađuje ili ažurira kontakt
agent.unavailable	Pokreće strategiju nedostupnosti obrasca za rezervacije (otkazivanje, preraspodjela, ponuda novog termina)
agent.available	Obavještava agenta o sastancima na čekanju

Uparivanje. RolChat traži kontakt najprije po e-pošti, a zatim po external_id koji je vaš dodatak ranije pohranio. Nije pronađen: izrađuje se lead ako je uključen sync_config.create_contacts, inače se događaj bilježi kao neuparen.

4. Gdje se prikazuju podaci dodatka

Kartice kontakata i tvrtki prikazuju odjeljak nazvan po vašem dodatku s poljima koja ste poslali, samo za čitanje, uz vrijeme posljednjeg ažuriranja. Iste podatke vraća i API:

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

Uvjeti automatizacije mogu provjeravati podatke dodataka, pa pravilo može usmjeriti razgovor prema korisnikovu paketu u vašem sustavu.

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

Objavljeni dodatak opisuje se u manifestu: naziv, kategorija, traženi opsezi, događaji na koje se pretplaćuje, obrazac postavki, neobavezni allowed_source_ips, recommended_rotation_days te cijena ako se naplaćuje. Manifest pokreće zaslon za povezivanje i pregled prije nego što se dodatak zajednice uvrsti u katalog.

Ograničenja i dobra praksa

• Dolazno tijelo do 5 MB; odlazno zadano 1 MB.
• API ključevi dodataka ograničeni su na 300 zahtjeva u minuti; dolazni webhookovi na 120 u minuti po dodatku.
• Dugotrajni neuspjesi isporuke označavaju dodatak kao degradiran; ako više od polovice isporuka ne uspijeva tijekom jednog sata, dodatak se pauzira, a administratori računa dobivaju obavijest.
• Nikada ne zapisujte niti vraćajte tajnu webhooka. Zamijenite je ako sumnjate da je otkrivena; zahvaljujući razdoblju preklapanja ništa se neće pokvariti.