Bou 'n inprop

’n Inprop is ’n HTTPS-eindpunt wat ondertekende gebeurtenisse van RolChat ontvang, plus opsionele oproepe wat dit terug na RolChat maak. Daar is geen kode om op te laai nie en geen looptyd om binne RolChat te huisves nie.

1. Registreer die inprop

In Instellings → Inproppe → Katalogus → Pasgemaak, of met die 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
  }
}

Die antwoord bevat die inprop-ID en die webhook-geheim, wat een keer gewys word. Stoor dit; elke gebeurtenis wat RolChat stuur, word daarmee onderteken, en elke gebeurtenis wat jy na RolChat stuur, moet ook daarmee onderteken wees.

2. Ontvang gebeurtenisse van RolChat

RolChat stuur na webhook_url_outbound wanneer dinge verander:

Gebeurtenis	Wanneer
chats.conversation.created	’n Gesprek begin
crm.contact.created	’n Kontak word geskep
crm.contact.updated	’n Kontak verander
tickets.ticket.created	’n Kaartjie word geskep
tickets.ticket.status_changed	’n Kaartjie skuif
marketing.meeting.booked	’n Vergadering word bespreek
marketing.meeting.cancelled	’n Vergadering word gekanselleer

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

Verifieer die handtekening, varsheid en nonce presies soos in Webhooks beskryf, antwoord vinnig 200, en ontdubbel volgens gebeurtenis-ID. Die breër gebeurtenisfamilies wat vir intekeninge beskikbaar is, is in die gebeurteniskatalogus.

3. Stuur gebeurtenisse na RolChat

Stuur na jou inprop se inkomende eindpunt, onderteken met dieselfde geheim:

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

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

Inkomende gebeurtenis	Wat RolChat doen
contact.data_updated	Stoor plugin_data op die ooreenstemmende kontak
company.data_updated	Stoor plugin_data op die ooreenstemmende maatskappy
contact.created_external	Skep of werk ’n kontak by
agent.unavailable	Voer die besprekingsvorm se onbeskikbaarheidstrategie uit (kanselleer, wys weer toe, bied ’n nuwe gleuf aan)
agent.available	Stel die agent in kennis van hangende vergaderings

Passing. RolChat soek die kontak eers volgens e-pos op, dan volgens die external_id wat jou inprop vroeër gestoor het. Nie gevind nie: ’n lead word geskep as sync_config.create_contacts aan is, anders word die gebeurtenis as ongepas aangeteken.

4. Waar inpropdata verskyn

Kontak- en maatskappykaarte wys ’n afdeling vernoem na jou inprop met die velde wat jy gestuur het, slegs-lees, met die tyd van die laaste bywerking. Dieselfde data word deur die API teruggegee:

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

Outomatiseringsvoorwaardes kan inpropdata toets, so ’n reël kan ’n gesprek roeteer volgens die kliënt se plan in jou stelsel.

5. Bestuurs-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. Manifes

’n Gepubliseerde inprop verklaar homself in ’n manifes: naam, kategorie, die omvange wat dit versoek, die gebeurtenisse waarop dit inteken, sy instellingsvorm, opsionele allowed_source_ips, recommended_rotation_days, en sy pryse as dit betaald is. Die manifes dryf die koppelskerm en die hersiening voordat ’n gemeenskapsinprop gelys word.

Limiete en higiëne

• Inkomende liggaam tot 5 MB; uitgaande 1 MB by verstek.
• Inprop-API-sleutels is beperk tot 300 versoeke per minuut; inkomende webhooks tot 120 per minuut per inprop.
• Volgehoue afleweringsmislukkings merk ’n inprop as verswak; as meer as die helfte vir ’n uur misluk, word dit onderbreek en die rekening se admins word in kennis gestel.
• Moet nooit die webhook-geheim aanteken of terugeggo nie. Roteer dit as jy blootstelling vermoed; die oorvleuelingsvenster beteken niks breek nie.