Bygg en plugin

En plugin er et HTTPS-endepunkt som mottar signerte hendelser fra RolChat, pluss valgfrie kall den gjør tilbake til RolChat. Det er ingen kode å laste opp og ikke noe kjøretidsmiljø å drifte inne i RolChat.

1. Registrer pluginen

I Innstillinger → Plugins → Katalog → Egendefinert, eller med API-et:

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

Svaret inneholder plugin-ID-en og webhook-hemmeligheten, som vises én gang. Ta vare på den; hver hendelse RolChat sender, signeres med den, og hver hendelse du sender til RolChat, må også være det.

2. Motta hendelser fra RolChat

RolChat sender POST til webhook_url_outbound når noe endres:

Hendelse	Når
chats.conversation.created	En samtale starter
crm.contact.created	En kontakt opprettes
crm.contact.updated	En kontakt endres
tickets.ticket.created	En sak opprettes
tickets.ticket.status_changed	En sak endrer status
marketing.meeting.booked	Et møte bookes
marketing.meeting.cancelled	Et møte avlyses

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

Verifiser signaturen, ferskheten og noncen nøyaktig slik det er beskrevet i Webhooks, svar 200 raskt, og fjern duplikater ut fra hendelses-ID-en. De bredere hendelsesfamiliene som er tilgjengelige for abonnementer, står i hendelseskatalogen.

3. Send hendelser til RolChat

Send POST til pluginens innkommende endepunkt, signert med den samme hemmeligheten:

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

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

Innkommende hendelse	Hva RolChat gjør
contact.data_updated	Lagrer plugin_data på den samsvarende kontakten
company.data_updated	Lagrer plugin_data på det samsvarende selskapet
contact.created_external	Oppretter eller oppdaterer en kontakt
agent.unavailable	Kjører bookingskjemaets strategi for utilgjengelighet (avlys, tildel på nytt, tilby et nytt tidspunkt)
agent.available	Varsler agenten om ventende møter

Samkjøring. RolChat slår først opp kontakten etter e-post, deretter etter external_id som pluginen din lagret tidligere. Ikke funnet: et lead opprettes hvis sync_config.create_contacts er på, ellers logges hendelsen som ikke samkjørt.

4. Hvor plugindata vises

Kontakt- og selskapskort viser en seksjon med navnet på pluginen din og feltene du sendte, skrivebeskyttet, med tidspunktet for siste oppdatering. De samme dataene returneres av API-et:

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

Automatiseringsbetingelser kan teste plugindata, så en regel kan rute en samtale etter kundens abonnement i systemet ditt.

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

En publisert plugin beskriver seg selv i et manifest: navn, kategori, tilgangsomfangene den ber om, hendelsene den abonnerer på, innstillingsskjemaet, valgfrie allowed_source_ips, recommended_rotation_days og prisen hvis den er betalt. Manifestet styrer tilkoblingsskjermbildet og gjennomgangen før en plugin fra fellesskapet blir oppført.

Grenser og god praksis

• Innkommende body opptil 5 MB; utgående 1 MB som standard.
• Plugin-API-nøkler er begrenset til 300 forespørsler per minutt; innkommende webhooks til 120 per minutt per plugin.
• Vedvarende leveringsfeil merker en plugin som svekket; hvis mer enn halvparten feiler i en time, settes den på pause, og kontoens administratorer varsles.
• Logg eller gjengi aldri webhook-hemmeligheten. Roter den hvis du mistenker at den er avslørt; overlappingsvinduet gjør at ingenting slutter å virke.