Bygg ett plugin

Ett plugin är en HTTPS-endpoint som tar emot signerade händelser från RolChat, plus valfria anrop som den gör tillbaka till RolChat. Det finns ingen kod att ladda upp och ingen körmiljö att drifta inuti RolChat.

1. Registrera pluginet

Under Inställningar → Plugins → Katalog → Anpassat, eller via 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 innehåller plugin-ID:t och webhook-hemligheten, som visas en gång. Spara den; varje händelse som RolChat skickar signeras med den, och varje händelse som du skickar till RolChat måste också vara det.

2. Ta emot händelser från RolChat

RolChat skickar POST till webhook_url_outbound när något ändras:

Händelse	När
chats.conversation.created	En konversation startar
crm.contact.created	En kontakt skapas
crm.contact.updated	En kontakt ändras
tickets.ticket.created	Ett ärende skapas
tickets.ticket.status_changed	Ett ärende byter status
marketing.meeting.booked	Ett möte bokas
marketing.meeting.cancelled	Ett möte avbokas

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

Verifiera signaturen, aktualiteten och nonce exakt som beskrivs under Webhooks, svara 200 snabbt och ta bort dubbletter utifrån händelse-ID. De bredare händelsefamiljerna som finns för prenumerationer står i händelsekatalogen.

3. Skicka händelser till RolChat

Skicka POST till pluginets inkommande endpoint, signerat med samma hemlighet:

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

Inkommande händelse	Vad RolChat gör
contact.data_updated	Sparar plugin_data på den matchande kontakten
company.data_updated	Sparar plugin_data på det matchande företaget
contact.created_external	Skapar eller uppdaterar en kontakt
agent.unavailable	Kör bokningsformulärets strategi för otillgänglighet (avboka, tilldela om, erbjud en ny tid)
agent.available	Meddelar agenten om väntande möten

Matchning. RolChat slår först upp kontakten via e-post och sedan via det external_id som ditt plugin sparade tidigare. Hittas inte: ett lead skapas om sync_config.create_contacts är på, annars loggas händelsen som omatchad.

4. Var plugindata visas

Kontakt- och företagskort visar ett avsnitt med ditt plugins namn och de fält du skickade, skrivskyddat, med tidpunkten för den senaste uppdateringen. Samma data returneras av API:et:

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

Automatiseringsvillkor kan testa plugindata, så en regel kan routa en konversation utifrån kundens plan i ditt system.

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

Ett publicerat plugin beskriver sig självt i ett manifest: namn, kategori, de behörighetsomfång det begär, de händelser det prenumererar på, dess inställningsformulär, valfria allowed_source_ips, recommended_rotation_days och dess pris om det är betalt. Manifestet styr anslutningsskärmen och granskningen innan ett communityplugin listas.

Gränser och god praxis

• Inkommande body upp till 5 MB; utgående 1 MB som standard.
• API-nycklar för plugins är begränsade till 300 förfrågningar per minut; inkommande webhooks till 120 per minut och plugin.
• Ihållande leveransfel markerar ett plugin som försämrat; om mer än hälften misslyckas under en timme pausas det och kontots administratörer meddelas.
• Logga eller eka aldrig webhook-hemligheten. Rotera den om du misstänker att den har exponerats; överlappsfönstret gör att inget går sönder.