Vytvořte plugin

Plugin je endpoint HTTPS, který přijímá podepsané události z RolChat, plus volitelná volání, která provádí zpět do RolChat. Nenahráváte žádný kód a uvnitř RolChat nic nehostujete.

1. Zaregistrujte plugin

V Nastavení → Pluginy → Katalog → Vlastní, nebo přes 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
  }
}

Odpověď obsahuje ID pluginu a tajný klíč webhooku, zobrazený jen jednou. Uložte si ho; každá událost, kterou RolChat pošle, je jím podepsaná a každá událost, kterou pošlete do RolChat, musí být také.

2. Přijímejte události z RolChat

RolChat posílá POST na webhook_url_outbound, když se něco změní:

Událost	Kdy
chats.conversation.created	Začne konverzace
crm.contact.created	Vytvoří se kontakt
crm.contact.updated	Kontakt se změní
tickets.ticket.created	Vytvoří se tiket
tickets.ticket.status_changed	Tiket změní stav
marketing.meeting.booked	Zarezervuje se schůzka
marketing.meeting.cancelled	Schůzka se zruší

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

Ověřte podpis, čerstvost a nonce přesně podle popisu ve Webhoocích, rychle odpovězte 200 a deduplikujte podle ID události. Širší rodiny událostí dostupné pro odběry najdete v katalogu událostí.

3. Posílejte události do RolChat

Posílejte POST na příchozí endpoint svého pluginu, podepsaný stejným tajným klíčem:

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

Odpověď: { "received": true, "matched_contact_id": "…" }.

Příchozí událost	Co RolChat udělá
contact.data_updated	Uloží plugin_data k odpovídajícímu kontaktu
company.data_updated	Uloží plugin_data k odpovídající firmě
contact.created_external	Vytvoří nebo aktualizuje kontakt
agent.unavailable	Spustí strategii nedostupnosti rezervačního formuláře (zrušení, přeřazení, nabídka nového termínu)
agent.available	Upozorní agenta na čekající schůzky

Párování. RolChat hledá kontakt nejprve podle e-mailu, pak podle external_id, které váš plugin dříve uložil. Nenalezen: pokud je zapnuté sync_config.create_contacts, vytvoří se lead, jinak se událost zaloguje jako nespárovaná.

4. Kde se data pluginu zobrazují

Karty kontaktů a firem ukazují sekci pojmenovanou podle vašeho pluginu s poli, která jste poslali, jen pro čtení a s časem poslední aktualizace. Stejná data vrací i API:

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

Podmínky automatizace mohou testovat data pluginů, takže pravidlo může směrovat konverzaci podle tarifu zákazníka ve vašem systému.

5. API pro správu

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

Zveřejněný plugin se popisuje v manifestu: název, kategorie, požadované rozsahy, odebírané události, formulář nastavení, volitelně allowed_source_ips, recommended_rotation_days a ceník, pokud je placený. Manifest řídí obrazovku připojení a kontrolu před zařazením komunitního pluginu do katalogu.

Limity a osvědčené postupy

• Příchozí tělo až 5 MB; odchozí ve výchozím stavu 1 MB.
• Klíče API pluginů jsou omezeny na 300 požadavků za minutu; příchozí webhooky na 120 za minutu na plugin.
• Trvalá selhání doručení označí plugin jako degradovaný; pokud víc než polovina doručení selhává po dobu hodiny, plugin se pozastaví a administrátoři účtu dostanou upozornění.
• Tajný klíč webhooku nikdy nelogujte ani nevracejte v odpovědích. Při podezření na únik ho vyměňte; díky překryvnému období se nic nerozbije.