Zbuduj wtyczkę

Wtyczka to endpoint HTTPS, który odbiera podpisane zdarzenia z RolChat, oraz opcjonalne wywołania, które wykonuje z powrotem do RolChat. Nie ma kodu do przesyłania ani środowiska uruchomieniowego do hostowania w RolChat.

1. Zarejestruj wtyczkę

W Ustawienia → Wtyczki → Katalog → Własna lub przez 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
  }
}

Odpowiedź zawiera identyfikator wtyczki i sekret webhooka, pokazywany raz. Zachowaj go; każde zdarzenie wysyłane przez RolChat jest nim podpisane i każde zdarzenie, które wysyłasz do RolChat, też musi być.

2. Odbieraj zdarzenia z RolChat

RolChat wysyła żądania POST na webhook_url_outbound, gdy coś się zmienia:

Zdarzenie	Kiedy
chats.conversation.created	Rozpoczyna się rozmowa
crm.contact.created	Utworzono kontakt
crm.contact.updated	Kontakt się zmienia
tickets.ticket.created	Utworzono zgłoszenie
tickets.ticket.status_changed	Zgłoszenie zmienia status
marketing.meeting.booked	Zarezerwowano spotkanie
marketing.meeting.cancelled	Anulowano spotkanie

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

Zweryfikuj podpis, świeżość i nonce dokładnie tak, jak opisano w Webhookach, szybko odpowiedz 200 i deduplikuj według identyfikatora zdarzenia. Szersze rodziny zdarzeń dostępne dla subskrypcji są w katalogu zdarzeń.

3. Wysyłaj zdarzenia do RolChat

Wysyłaj żądania POST na endpoint przychodzący swojej wtyczki, podpisane tym samym sekretem:

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

Odpowiedź: { "received": true, "matched_contact_id": "…" }.

Zdarzenie przychodzące	Co robi RolChat
contact.data_updated	Zapisuje plugin_data w dopasowanym kontakcie
company.data_updated	Zapisuje plugin_data w dopasowanej firmie
contact.created_external	Tworzy lub aktualizuje kontakt
agent.unavailable	Uruchamia strategię niedostępności formularza rezerwacji (anulowanie, ponowne przypisanie, propozycja nowego terminu)
agent.available	Powiadamia agenta o oczekujących spotkaniach

Dopasowywanie. RolChat szuka kontaktu najpierw po e-mailu, potem po external_id, który Twoja wtyczka zapisała wcześniej. Nie znaleziono: tworzony jest lead, jeśli włączone jest sync_config.create_contacts, w przeciwnym razie zdarzenie jest logowane jako niedopasowane.

4. Gdzie pojawiają się dane wtyczki

Karty kontaktów i firm pokazują sekcję nazwaną od Twojej wtyczki z przesłanymi polami, tylko do odczytu, z czasem ostatniej aktualizacji. Te same dane zwraca API:

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

Warunki automatyzacji mogą sprawdzać dane wtyczek, więc reguła może kierować rozmowę według planu klienta w Twoim systemie.

5. API zarządzania

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

Opublikowana wtyczka opisuje się w manifeście: nazwa, kategoria, żądane zakresy, subskrybowane zdarzenia, formularz ustawień, opcjonalne allowed_source_ips, recommended_rotation_days oraz cennik, jeśli jest płatna. Manifest steruje ekranem podłączania i przeglądem przed umieszczeniem wtyczki społeczności w katalogu.

Limity i dobre praktyki

• Treść przychodząca do 5 MB; wychodząca domyślnie 1 MB.
• Klucze API wtyczek są ograniczone do 300 żądań na minutę; przychodzące webhooki do 120 na minutę na wtyczkę.
• Utrzymujące się błędy dostarczania oznaczają wtyczkę jako działającą z problemami; jeśli ponad połowa dostarczeń zawodzi przez godzinę, wtyczka jest wstrzymywana, a administratorzy konta dostają powiadomienie.
• Nigdy nie loguj ani nie odsyłaj sekretu webhooka. Zmień go, jeśli podejrzewasz wyciek; okno nakładania się sprawia, że nic się nie zepsuje.