Ein Plugin entwickeln

Ein Plugin ist ein HTTPS-Endpunkt, der signierte Ereignisse von RolChat empfängt, plus optionale Aufrufe, die er an RolChat zurücksendet. Es gibt keinen Code hochzuladen und keine Laufzeitumgebung innerhalb von RolChat zu betreiben.

1. Das Plugin registrieren

Unter Einstellungen → Plugins → Katalog → Benutzerdefiniert oder über die 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
  }
}

Die Antwort enthält die Plugin-ID und das Webhook-Geheimnis, das einmal angezeigt wird. Bewahren Sie es auf; jedes Ereignis, das RolChat sendet, ist damit signiert, und jedes Ereignis, das Sie an RolChat senden, muss es ebenfalls sein.

2. Ereignisse von RolChat empfangen

RolChat sendet an webhook_url_outbound, wenn sich etwas ändert:

Ereignis	Wann
chats.conversation.created	Eine Konversation beginnt
crm.contact.created	Ein Kontakt wird angelegt
crm.contact.updated	Ein Kontakt ändert sich
tickets.ticket.created	Ein Ticket wird erstellt
tickets.ticket.status_changed	Ein Ticket wechselt den Status
marketing.meeting.booked	Ein Termin wird gebucht
marketing.meeting.cancelled	Ein Termin wird abgesagt

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

Prüfen Sie Signatur, Aktualität und Nonce genau wie unter Webhooks beschrieben, antworten Sie schnell mit 200 und deduplizieren Sie nach Ereignis-ID. Die umfassenderen Ereignisgruppen, die für Abonnements verfügbar sind, stehen im Ereigniskatalog.

3. Ereignisse an RolChat senden

Senden Sie an den eingehenden Endpunkt Ihres Plugins, signiert mit demselben Geheimnis:

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

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

Eingehendes Ereignis	Was RolChat tut
contact.data_updated	Speichert plugin_data am passenden Kontakt
company.data_updated	Speichert plugin_data am passenden Unternehmen
contact.created_external	Legt einen Kontakt an oder aktualisiert ihn
agent.unavailable	Führt die Nichtverfügbarkeitsstrategie des Buchungsformulars aus (absagen, neu zuweisen, neues Zeitfenster anbieten)
agent.available	Benachrichtigt den Agenten über ausstehende Termine

Abgleich. RolChat sucht den Kontakt zuerst nach E-Mail-Adresse, dann nach der external_id, die Ihr Plugin zuvor gespeichert hat. Nicht gefunden: Ein Lead wird angelegt, wenn sync_config.create_contacts aktiv ist, andernfalls wird das Ereignis als nicht zugeordnet protokolliert.

4. Wo Plugin-Daten erscheinen

Kontakt- und Unternehmenskarten zeigen einen nach Ihrem Plugin benannten Abschnitt mit den gesendeten Feldern, schreibgeschützt, mit dem Zeitpunkt der letzten Aktualisierung. Dieselben Daten liefert die API:

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

Automatisierungsbedingungen können Plugin-Daten prüfen, sodass eine Regel eine Konversation nach dem Tarif des Kunden in Ihrem System weiterleiten kann.

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

Ein veröffentlichtes Plugin beschreibt sich selbst in einem Manifest: Name, Kategorie, die angeforderten Scopes, die abonnierten Ereignisse, sein Einstellungsformular, optional allowed_source_ips, recommended_rotation_days und bei kostenpflichtigen Plugins den Preis. Das Manifest steuert den Verbindungsbildschirm und die Prüfung, bevor ein Community-Plugin gelistet wird.

Limits und Sorgfalt

• Eingehender Body bis 5 MB; ausgehend standardmäßig 1 MB.
• Plugin-API-Schlüssel sind auf 300 Anfragen pro Minute begrenzt; eingehende Webhooks auf 120 pro Minute und Plugin.
• Anhaltende Zustellfehler markieren ein Plugin als beeinträchtigt; schlägt über eine Stunde mehr als die Hälfte fehl, wird es pausiert, und die Administratoren des Kontos werden benachrichtigt.
• Protokollieren oder wiederholen Sie das Webhook-Geheimnis nie. Rotieren Sie es, wenn Sie eine Offenlegung vermuten; dank des Überlappungsfensters geht dabei nichts kaputt.