Spraudņa izveide

Spraudnis ir HTTPS galapunkts, kas saņem parakstītus notikumus no RolChat, kā arī neobligāti izsaukumi, ko tas veic atpakaļ uz RolChat. Nav koda, ko augšupielādēt, un nav izpildvides, ko mitināt RolChat iekšienē.

1. Reģistrējiet spraudni

Sadaļā Iestatījumi → Spraudņi → Katalogs → Pielāgots vai ar 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
  }
}

Atbilde satur spraudņa ID un webhook noslēpumu, kas tiek parādīts vienreiz. Saglabājiet to; katrs notikums, ko sūta RolChat, ir ar to parakstīts, un tāpat jāparaksta katrs notikums, ko jūs sūtāt uz RolChat.

2. Saņemiet notikumus no RolChat

RolChat sūta datus uz webhook_url_outbound, kad kaut kas mainās:

Notikums	Kad
chats.conversation.created	Sākas saruna
crm.contact.created	Tiek izveidots kontakts
crm.contact.updated	Mainās kontakts
tickets.ticket.created	Tiek izveidots pieteikums
tickets.ticket.status_changed	Pieteikums pārvietojas
marketing.meeting.booked	Tiek rezervēta tikšanās
marketing.meeting.cancelled	Tikšanās tiek atcelta

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

Pārbaudiet parakstu, svaigumu un nonce tieši tā, kā aprakstīts lapā Webhooks, ātri atbildiet ar 200 un novērsiet dublikātus pēc notikuma ID. Plašākas notikumu saimes, kas pieejamas abonementiem, ir notikumu katalogā.

3. Sūtiet notikumus uz RolChat

Sūtiet datus uz sava spraudņa ienākošo galapunktu, parakstot ar to pašu noslēpumu:

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

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

Ienākošais notikums	Ko dara RolChat
contact.data_updated	Saglabā plugin_data atbilstošajā kontaktā
company.data_updated	Saglabā plugin_data atbilstošajā uzņēmumā
contact.created_external	Izveido vai atjaunina kontaktu
agent.unavailable	Izpilda rezervēšanas veidlapas nepieejamības stratēģiju (atcelt, pārpiešķirt, piedāvāt jaunu laiku)
agent.available	Paziņo aģentam par gaidāmajām tikšanās reizēm

Sasaiste. RolChat vispirms meklē kontaktu pēc e-pasta, pēc tam pēc external_id, ko jūsu spraudnis saglabāja iepriekš. Nav atrasts: tiek izveidots potenciālais klients, ja ir ieslēgts sync_config.create_contacts, citādi notikums tiek reģistrēts kā nesasaistīts.

4. Kur parādās spraudņa dati

Kontaktu un uzņēmumu kartītēs ir sadaļa ar jūsu spraudņa nosaukumu un jūsu nosūtītajiem laukiem, tikai lasāma, ar pēdējās atjaunināšanas laiku. Tos pašus datus atgriež API:

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

Automatizācijas nosacījumi var pārbaudīt spraudņa datus, tāpēc noteikums var maršrutēt sarunu pēc klienta plāna jūsu sistēmā.

5. Pārvaldības 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. Manifests

Publicēts spraudnis sevi apraksta manifestā: nosaukums, kategorija, pieprasītie tvērumi, abonētie notikumi, iestatījumu veidlapa, neobligāti allowed_source_ips, recommended_rotation_days un cena, ja tas ir maksas. Manifests nosaka pievienošanas ekrānu un pārbaudi, pirms kopienas spraudnis tiek iekļauts sarakstā.

Ierobežojumi un higiēna

• Ienākošais saturs līdz 5 MB; izejošais pēc noklusējuma 1 MB.
• Spraudņu API atslēgas ir ierobežotas līdz 300 pieprasījumiem minūtē; ienākošie webhook līdz 120 minūtē vienam spraudnim.
• Ilgstošas piegādes kļūmes atzīmē spraudni kā pasliktinātu; ja stundas laikā neizdodas vairāk nekā puse, spraudnis tiek apturēts un konta administratori saņem paziņojumu.
• Nekad nereģistrējiet žurnālā un neatgrieziet webhook noslēpumu. Rotējiet to, ja jums ir aizdomas par noplūdi; pārklāšanās logs nozīmē, ka nekas nesabojājas.