Rakenna laajennus

Laajennus on HTTPS-päätepiste, joka vastaanottaa allekirjoitettuja tapahtumia RolChatilta, sekä valinnaiset kutsut, joita se tekee takaisin RolChatiin. Mitään koodia ei ladata eikä mitään ajonaikaista ympäristöä isännöidä RolChatin sisällä.

1. Rekisteröi laajennus

Kohdassa Asetukset → Laajennukset → Luettelo → Mukautettu tai API:lla:

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

Vastaus sisältää laajennuksen tunnisteen ja webhookin salaisuuden, joka näytetään kerran. Tallenna se; jokainen RolChatin lähettämä tapahtuma allekirjoitetaan sillä, ja jokaisen RolChatiin lähettämäsi tapahtuman on oltava samoin allekirjoitettu.

2. Vastaanota tapahtumia RolChatilta

RolChat lähettää webhook_url_outbound-osoitteeseen, kun asiat muuttuvat:

Tapahtuma	Milloin
chats.conversation.created	Keskustelu alkaa
crm.contact.created	Kontakti luodaan
crm.contact.updated	Kontakti muuttuu
tickets.ticket.created	Tiketti luodaan
tickets.ticket.status_changed	Tiketti siirtyy tilasta toiseen
marketing.meeting.booked	Tapaaminen varataan
marketing.meeting.cancelled	Tapaaminen perutaan

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

Tarkista allekirjoitus, tuoreus ja nonce täsmälleen kuten sivulla Webhookit kuvataan, vastaa 200 nopeasti ja poista kaksoiskappaleet tapahtuman tunnisteen perusteella. Tilauksille saatavilla olevat laajemmat tapahtumaperheet ovat tapahtumaluettelossa.

3. Lähetä tapahtumia RolChatiin

Lähetä laajennuksesi saapuvien tapahtumien päätepisteeseen samalla salaisuudella allekirjoitettuna:

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

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

Saapuva tapahtuma	Mitä RolChat tekee
contact.data_updated	Tallentaa plugin_data-tiedot vastaavalle kontaktille
company.data_updated	Tallentaa plugin_data-tiedot vastaavalle yritykselle
contact.created_external	Luo tai päivittää kontaktin
agent.unavailable	Suorittaa varauslomakkeen poissaolostrategian (peruutus, uudelleenosoitus, uuden ajan tarjoaminen)
agent.available	Ilmoittaa agentille odottavista tapaamisista

Vastaavuus. RolChat etsii kontaktia ensin sähköpostin perusteella ja sitten external_id-arvolla, jonka laajennuksesi tallensi aiemmin. Ei löytynyt: liidi luodaan, jos sync_config.create_contacts on käytössä, muuten tapahtuma kirjataan vastaamattomaksi.

4. Missä laajennuksen tiedot näkyvät

Kontakti- ja yrityskorteissa näkyy laajennuksesi mukaan nimetty osio lähettämilläsi kentillä, vain luku -muodossa ja viimeisimmän päivityksen ajankohdan kera. API palauttaa samat tiedot:

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

Automaation ehdot voivat testata laajennuksen tietoja, joten sääntö voi reitittää keskustelun asiakkaan järjestelmässäsi olevan paketin perusteella.

5. Hallinta-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. Manifesti

Julkaistu laajennus kuvaa itsensä manifestissa: nimi, kategoria, pyytämänsä oikeusalueet, tilaamansa tapahtumat, asetuslomake, valinnainen allowed_source_ips, recommended_rotation_days ja hinnoittelu, jos laajennus on maksullinen. Manifesti ohjaa yhdistämisnäkymää ja tarkastusta ennen kuin yhteisön laajennus lisätään luetteloon.

Rajat ja hyvät käytännöt

• Saapuva runko enintään 5 Mt; lähtevä oletuksena 1 Mt.
• Laajennusten API-avaimet on rajoitettu 300 pyyntöön minuutissa; saapuvat webhookit 120:een minuutissa laajennusta kohden.
• Jatkuvat toimitusvirheet merkitsevät laajennuksen heikentyneeksi; jos yli puolet epäonnistuu tunnin ajan, laajennus keskeytetään ja tilin ylläpitäjille ilmoitetaan.
• Älä koskaan kirjaa lokiin tai tulosta webhookin salaisuutta. Kierrätä se, jos epäilet sen paljastuneen; päällekkäisyysikkunan ansiosta mikään ei rikkoudu.