Construiește un plugin

Un plugin este un endpoint HTTPS care primește evenimente semnate de la RolChat, plus apeluri opționale pe care le face înapoi către RolChat. Nu există cod de încărcat și nici mediu de rulare de găzduit în RolChat.

1. Înregistrează pluginul

În Setări → Pluginuri → Catalog → Personalizat sau prin 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
  }
}

Răspunsul conține ID-ul pluginului și secretul webhook-ului, afișat o singură dată. Păstrează-l: fiecare eveniment trimis de RolChat este semnat cu el și la fel trebuie să fie fiecare eveniment pe care îl trimiți tu către RolChat.

2. Primește evenimente de la RolChat

RolChat trimite cereri către webhook_url_outbound când se schimbă ceva:

Eveniment	Când
chats.conversation.created	Începe o conversație
crm.contact.created	Este creat un contact
crm.contact.updated	Un contact se schimbă
tickets.ticket.created	Este creat un tichet
tickets.ticket.status_changed	Un tichet își schimbă starea
marketing.meeting.booked	Este programată o întâlnire
marketing.meeting.cancelled	Este anulată o întâlnire

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

Verifică semnătura, prospețimea și nonce-ul exact cum este descris în Webhook-uri, răspunde rapid 200 și elimină duplicatele după ID-ul evenimentului. Familiile mai largi de evenimente disponibile pentru abonamente se află în catalogul evenimentelor.

3. Trimite evenimente către RolChat

Trimite cereri către endpointul de intrare al pluginului tău, semnate cu același secret:

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

Răspuns: { "received": true, "matched_contact_id": "…" }.

Eveniment primit	Ce face RolChat
contact.data_updated	Stochează plugin_data pe contactul corespunzător
company.data_updated	Stochează plugin_data pe compania corespunzătoare
contact.created_external	Creează sau actualizează un contact
agent.unavailable	Rulează strategia de indisponibilitate a formularului de programare (anulare, reatribuire, propunerea unui nou interval)
agent.available	Anunță agentul despre întâlnirile în așteptare

Potrivire. RolChat caută contactul mai întâi după e-mail, apoi după external_id stocat anterior de pluginul tău. Dacă nu îl găsește, se creează un lead când sync_config.create_contacts este activ; altfel evenimentul este înregistrat ca nepotrivit.

4. Unde apar datele pluginului

Fișele contactelor și ale companiilor afișează o secțiune cu numele pluginului tău, cu câmpurile trimise, doar în citire, și cu ora ultimei actualizări. Aceleași date sunt returnate de API:

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

Condițiile de automatizare pot testa datele pluginului, așa că o regulă poate direcționa o conversație în funcție de planul clientului din sistemul tău.

5. API-ul de gestionare

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

Un plugin publicat se descrie într-un manifest: nume, categorie, domeniile de acces solicitate, evenimentele la care se abonează, formularul de setări, allowed_source_ips opțional, recommended_rotation_days și prețul, dacă este plătit. Manifestul determină ecranul de conectare și verificarea făcută înainte ca un plugin al comunității să fie listat.

Limite și bune practici

• Corpul primit de până la 5 MB; cel trimis, 1 MB implicit.
• Cheile API de plugin sunt limitate la 300 de cereri pe minut; webhook-urile primite, la 120 pe minut per plugin.
• Eșecurile repetate de livrare marchează un plugin ca degradat; dacă peste jumătate dintre livrări eșuează timp de o oră, pluginul este pus pe pauză, iar administratorii contului sunt anunțați.
• Nu înregistra și nu afișa niciodată secretul webhook-ului. Rotește-l dacă bănuiești că a fost expus; datorită ferestrei de suprapunere, nimic nu se strică.