Crea un plugin

Un plugin è un endpoint HTTPS che riceve eventi firmati da RolChat, più eventuali chiamate che effettua a sua volta verso RolChat. Non c’è codice da caricare né runtime da ospitare dentro RolChat.

1. Registra il plugin

In Impostazioni → Plugin → Catalogo → Personalizzato, oppure con l’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
  }
}

La risposta contiene l’ID del plugin e il segreto webhook, mostrato una sola volta. Conservalo: ogni evento che RolChat invia è firmato con esso, e deve esserlo anche ogni evento che invii tu a RolChat.

2. Ricevi eventi da RolChat

RolChat invia dati a webhook_url_outbound quando qualcosa cambia:

Evento	Quando
chats.conversation.created	Inizia una conversazione
crm.contact.created	Viene creato un contatto
crm.contact.updated	Cambia un contatto
tickets.ticket.created	Viene creato un ticket
tickets.ticket.status_changed	Un ticket cambia stato
marketing.meeting.booked	Viene prenotato un appuntamento
marketing.meeting.cancelled	Viene annullato un appuntamento

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

Verifica firma, validità temporale e nonce esattamente come descritto in Webhook, rispondi 200 rapidamente e deduplica per ID evento. Le famiglie di eventi più ampie disponibili per le iscrizioni sono nel catalogo degli eventi.

3. Invia eventi a RolChat

Invia i dati all’endpoint in entrata del tuo plugin, firmati con lo stesso segreto:

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

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

Evento in entrata	Cosa fa RolChat
contact.data_updated	Salva plugin_data sul contatto corrispondente
company.data_updated	Salva plugin_data sull’azienda corrispondente
contact.created_external	Crea o aggiorna un contatto
agent.unavailable	Esegue la strategia di indisponibilità del modulo di prenotazione (annullare, riassegnare, proporre un nuovo slot)
agent.available	Avvisa l’agente degli appuntamenti in sospeso

Abbinamento. RolChat cerca il contatto prima per email, poi per l’external_id che il tuo plugin ha salvato in precedenza. Se non lo trova: viene creato un lead se sync_config.create_contacts è attivo, altrimenti l’evento viene registrato come non abbinato.

4. Dove compaiono i dati del plugin

Le schede di contatti e aziende mostrano una sezione con il nome del tuo plugin e i campi che hai inviato, in sola lettura, con l’orario dell’ultimo aggiornamento. Gli stessi dati vengono restituiti dall’API:

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

Le condizioni di automazione possono valutare i dati del plugin, quindi una regola può instradare una conversazione in base al piano del cliente nel tuo sistema.

5. API di gestione

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 pubblicato si dichiara in un manifest: nome, categoria, gli scope che richiede, gli eventi a cui si iscrive, il suo modulo di impostazioni, eventuali allowed_source_ips, recommended_rotation_days e il prezzo se è a pagamento. Il manifest determina la schermata di collegamento e la revisione che precede la pubblicazione di un plugin della community nel catalogo.

Limiti e buone pratiche

• Corpo in entrata fino a 5 MB; in uscita 1 MB per impostazione predefinita.
• Le chiavi API dei plugin sono limitate a 300 richieste al minuto; i webhook in entrata a 120 al minuto per plugin.
• Errori di consegna persistenti contrassegnano un plugin come degradato; se oltre la metà delle consegne fallisce per un’ora, il plugin viene messo in pausa e gli amministratori dell’account vengono avvisati.
• Non registrare né restituire mai il segreto webhook. Ruotalo se sospetti che sia stato esposto; grazie alla finestra di sovrapposizione non si rompe nulla.