Byg et plugin

Et plugin er et HTTPS-endpoint, der modtager signerede hændelser fra RolChat, plus valgfrie kald, det selv foretager tilbage til RolChat. Der er ingen kode at uploade og intet runtime at hoste inde i RolChat.

1. Registrér pluginet

Under Indstillinger → Plugins → Katalog → Brugerdefineret 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 indeholder pluginets id og webhookhemmeligheden, der vises én gang. Gem den; hver hændelse, RolChat sender, er signeret med den, og det samme skal hver hændelse, du sender til RolChat, være.

2. Modtag hændelser fra RolChat

RolChat sender en POST til webhook_url_outbound, når noget ændrer sig:

Hændelse	Hvornår
chats.conversation.created	En samtale starter
crm.contact.created	En kontakt oprettes
crm.contact.updated	En kontakt ændres
tickets.ticket.created	En ticket oprettes
tickets.ticket.status_changed	En ticket skifter status
marketing.meeting.booked	Et møde bookes
marketing.meeting.cancelled	Et møde aflyses

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

Verificér signaturen, aktualiteten og noncen præcis som beskrevet under Webhooks, svar hurtigt 200, og dedupliker efter hændelses-id. De bredere hændelsesfamilier, der kan abonneres på, står i hændelseskataloget.

3. Send hændelser til RolChat

Send en POST til dit plugins indgående endpoint, signeret med den samme hemmelighed:

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

Indgående hændelse	Hvad RolChat gør
contact.data_updated	Gemmer plugin_data på den matchende kontakt
company.data_updated	Gemmer plugin_data på den matchende virksomhed
contact.created_external	Opretter eller opdaterer en kontakt
agent.unavailable	Kører bookingformularens strategi for utilgængelighed (aflys, omfordel, tilbyd et nyt tidspunkt)
agent.available	Giver agenten besked om ventende møder

Matchning. RolChat slår først kontakten op efter e-mail og derefter efter det external_id, dit plugin gemte tidligere. Ikke fundet: der oprettes et lead, hvis sync_config.create_contacts er slået til, ellers logges hændelsen som ikke matchet.

4. Hvor plugindata vises

Kontakt- og virksomhedskort viser et afsnit opkaldt efter dit plugin med de felter, du har sendt, skrivebeskyttet og med tidspunktet for den seneste opdatering. De samme data returneres af 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 sende en samtale videre ud fra kundens plan i dit system.

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

Et udgivet plugin beskriver sig selv i et manifest: navn, kategori, de scopes, det anmoder om, de hændelser, det abonnerer på, dets indstillingsformular, valgfrie allowed_source_ips, recommended_rotation_days og dets pris, hvis det er betalt. Manifestet styrer forbindelsesskærmen og gennemgangen, før et community-plugin bliver optaget i kataloget.

Grænser og god praksis

• Indgående body op til 5 MB; udgående 1 MB som standard.
• Plugin-API-nøgler er begrænset til 300 anmodninger pr. minut; indgående webhooks til 120 pr. minut pr. plugin.
• Vedvarende leveringsfejl markerer et plugin som forringet; fejler mere end halvdelen i en time, sættes det på pause, og kontoens administratorer får besked.
• Log eller gentag aldrig webhookhemmeligheden. Rotér den, hvis du har mistanke om, at den er blevet eksponeret; overlapningsvinduet betyder, at intet går i stykker.