Een plug-in bouwen

Een plug-in is een HTTPS-endpoint dat ondertekende gebeurtenissen van RolChat ontvangt, plus optionele aanroepen die het terug naar RolChat doet. Er is geen code om te uploaden en geen runtime om binnen RolChat te hosten.

1. Registreer de plug-in

In Instellingen → Plug-ins → Catalogus → Aangepast, of via de 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
  }
}

De response bevat de ID van de plug-in en het webhookgeheim, dat één keer wordt getoond. Bewaar het; elke gebeurtenis die RolChat verstuurt, is ermee ondertekend, en elke gebeurtenis die jij naar RolChat stuurt, moet dat ook zijn.

2. Gebeurtenissen van RolChat ontvangen

RolChat stuurt naar webhook_url_outbound wanneer er iets verandert:

Gebeurtenis	Wanneer
chats.conversation.created	Er begint een gesprek
crm.contact.created	Er wordt een contact aangemaakt
crm.contact.updated	Een contact verandert
tickets.ticket.created	Er wordt een ticket aangemaakt
tickets.ticket.status_changed	Een ticket verandert van status
marketing.meeting.booked	Er wordt een afspraak geboekt
marketing.meeting.cancelled	Een afspraak wordt geannuleerd

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

Verifieer de handtekening, versheid en nonce precies zoals beschreven in Webhooks, antwoord snel met 200 en ontdubbel op gebeurtenis-ID. De bredere gebeurtenisfamilies die voor abonnementen beschikbaar zijn, staan in de gebeurteniscatalogus.

3. Gebeurtenissen naar RolChat sturen

Stuur naar het inkomende endpoint van je plug-in, ondertekend met hetzelfde geheim:

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

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

Inkomende gebeurtenis	Wat RolChat doet
contact.data_updated	Slaat plugin_data op bij het bijbehorende contact
company.data_updated	Slaat plugin_data op bij het bijbehorende bedrijf
contact.created_external	Maakt een contact aan of werkt het bij
agent.unavailable	Voert de onbeschikbaarheidsstrategie van het boekingsformulier uit (annuleren, opnieuw toewijzen, een nieuw tijdslot aanbieden)
agent.available	Stuurt de agent een melding over openstaande afspraken

Matching. RolChat zoekt het contact eerst op e-mailadres en daarna op de external_id die je plug-in eerder heeft opgeslagen. Niet gevonden: er wordt een lead aangemaakt als sync_config.create_contacts aanstaat; anders wordt de gebeurtenis als niet-gematcht gelogd.

4. Waar plug-ingegevens verschijnen

Contact- en bedrijfskaarten tonen een sectie met de naam van je plug-in, met de velden die je hebt gestuurd, alleen-lezen, met het tijdstip van de laatste update. Dezelfde gegevens komen terug via de API:

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

Automatiseringsvoorwaarden kunnen plug-ingegevens testen, zodat een regel een gesprek kan routeren op basis van het abonnement van de klant in jouw systeem.

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

Een gepubliceerde plug-in beschrijft zichzelf in een manifest: naam, categorie, de gevraagde scopes, de gebeurtenissen waarop hij zich abonneert, zijn instellingenformulier, optioneel allowed_source_ips, recommended_rotation_days en de prijs als hij betaald is. Het manifest stuurt het verbindingsscherm en de beoordeling aan voordat een communityplug-in in de catalogus komt.

Limieten en hygiëne

• Inkomende body tot 5 MB; uitgaand standaard 1 MB.
• API-sleutels van plug-ins zijn beperkt tot 300 verzoeken per minuut; inkomende webhooks tot 120 per minuut per plug-in.
• Aanhoudende leveringsfouten markeren een plug-in als verminderd; faalt meer dan de helft gedurende een uur, dan wordt hij gepauzeerd en krijgen de beheerders van het account een melding.
• Log of toon het webhookgeheim nooit. Roteer het als je vermoedt dat het is uitgelekt; dankzij het overlapvenster gaat er niets stuk.