Bumuo ng plugin

Ang plugin ay HTTPS endpoint na tumatanggap ng mga naka-sign na event mula sa RolChat, kasama ang mga opsyonal na tawag na ginagawa nito pabalik sa RolChat. Walang code na ia-upload at walang runtime na iho-host sa loob ng RolChat.

1. I-register ang plugin

Sa Mga Setting → Mga Plugin → Catalogue → Custom, o gamit ang 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
  }
}

Naglalaman ang sagot ng plugin ID at ng webhook secret, na isang beses lang ipinapakita. Itabi ito; naka-sign dito ang bawat event na ipinapadala ng RolChat, at dapat ding naka-sign dito ang bawat event na ipinapadala mo sa RolChat.

2. Tumanggap ng mga event mula sa RolChat

Nagpo-post ang RolChat sa webhook_url_outbound kapag may nagbago:

Event	Kailan
chats.conversation.created	Nagsimula ang usapan
crm.contact.created	Nagawa ang contact
crm.contact.updated	Nagbago ang contact
tickets.ticket.created	Nagawa ang ticket
tickets.ticket.status_changed	Lumipat ang ticket
marketing.meeting.booked	Na-book ang meeting
marketing.meeting.cancelled	Nakansela ang meeting

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

I-verify ang signature, pagiging bago at nonce nang eksakto gaya ng inilarawan sa Mga webhook, sumagot ng 200 nang mabilis, at i-deduplicate ayon sa event ID. Nasa katalogo ng event ang mas malawak na mga pamilya ng event na available para sa mga subscription.

3. Magpadala ng mga event sa RolChat

Mag-post sa inbound endpoint ng plugin mo, naka-sign sa parehong 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" }
  }
}

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

Papasok na event	Ano ang ginagawa ng RolChat
contact.data_updated	Iniimbak ang plugin_data sa tumutugmang contact
company.data_updated	Iniimbak ang plugin_data sa tumutugmang kumpanya
contact.created_external	Gumagawa o nag-a-update ng contact
agent.unavailable	Pinapatakbo ang estratehiya ng booking form para sa hindi availability (kanselahin, i-reassign, mag-alok ng bagong slot)
agent.available	Nino-notify ang agent tungkol sa mga nakabinbing meeting

Pagtutugma. Hinahanap muna ng RolChat ang contact ayon sa e-mail, tapos ayon sa external_id na naunang inimbak ng plugin mo. Kung hindi nakita: gumagawa ng lead kung naka-on ang sync_config.create_contacts, kung hindi ay nila-log ang event bilang hindi tugma.

4. Saan lumalabas ang data ng plugin

Nagpapakita ang mga card ng contact at kumpanya ng seksyong ipinangalan sa plugin mo na may mga field na ipinadala mo, read-only, kasama ang oras ng huling update. Parehong data ang ibinabalik ng API:

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

Nasusuri ng mga kondisyon ng automation ang data ng plugin, kaya puwedeng iruta ng isang rule ang usapan ayon sa plan ng customer sa system mo.

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

Idinedeklara ng na-publish na plugin ang sarili nito sa isang manifest: pangalan, kategorya, ang mga scope na hinihingi nito, ang mga event na sina-subscribe-an nito, ang settings form nito, opsyonal na allowed_source_ips, recommended_rotation_days, at ang presyo nito kung may bayad. Ang manifest ang nagpapatakbo sa connect screen at sa review bago mailista ang isang community plugin.

Mga limitasyon at kalinisan

• Papasok na body hanggang 5 MB; palabas na 1 MB bilang default.
• Limitado ang mga plugin API key sa 300 request kada minuto; ang mga papasok na webhook sa 120 kada minuto kada plugin.
• Minamarkahang degraded ang plugin kapag tuloy-tuloy ang pagkabigo ng delivery; kapag higit sa kalahati ang bumibigo nang isang oras, pino-pause ito at nino-notify ang mga admin ng account.
• Huwag kailanman i-log o i-echo ang webhook secret. I-rotate ito kung pinaghihinalaan mong nalantad ito; dahil sa overlap window, walang masisira.