Créer un plugin

Un plugin est un endpoint HTTPS qui reçoit des événements signés de RolChat, auquel s’ajoutent d’éventuels appels qu’il effectue vers RolChat. Il n’y a aucun code à téléverser ni aucun environnement d’exécution à héberger dans RolChat.

1. Enregistrer le plugin

Dans Paramètres → Plugins → Catalogue → Personnalisé, ou avec 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 réponse contient l’identifiant du plugin et le secret de webhook, affiché une seule fois. Conservez-le : chaque événement envoyé par RolChat est signé avec, et chaque événement que vous envoyez à RolChat doit l’être aussi.

2. Recevoir des événements de RolChat

RolChat envoie une requête à webhook_url_outbound lorsque quelque chose change :

Événement	Quand
chats.conversation.created	Une conversation commence
crm.contact.created	Un contact est créé
crm.contact.updated	Un contact change
tickets.ticket.created	Un ticket est créé
tickets.ticket.status_changed	Un ticket change de statut
marketing.meeting.booked	Un rendez-vous est réservé
marketing.meeting.cancelled	Un rendez-vous est annulé

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

Vérifiez la signature, la fraîcheur et le nonce exactement comme décrit dans Webhooks, répondez 200 rapidement et dédoublonnez par identifiant d’événement. L’ensemble des familles d’événements disponibles pour les abonnements figure dans le catalogue des événements.

3. Envoyer des événements à RolChat

Envoyez vos requêtes à l’endpoint entrant de votre plugin, signées avec le même 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éponse : { "received": true, "matched_contact_id": "…" }.

Événement entrant	Action de RolChat
contact.data_updated	Enregistre plugin_data sur le contact correspondant
company.data_updated	Enregistre plugin_data sur l’entreprise correspondante
contact.created_external	Crée ou met à jour un contact
agent.unavailable	Applique la stratégie d’indisponibilité du formulaire de réservation (annuler, réattribuer, proposer un nouveau créneau)
agent.available	Informe l’agent des rendez-vous en attente

Rapprochement. RolChat recherche d’abord le contact par e-mail, puis par l’external_id que votre plugin a enregistré auparavant. S’il n’est pas trouvé, un prospect est créé si sync_config.create_contacts est activé ; sinon, l’événement est journalisé comme non rapproché.

4. Où apparaissent les données du plugin

Les fiches de contacts et d’entreprises affichent une section au nom de votre plugin avec les champs envoyés, en lecture seule, ainsi que l’heure de la dernière mise à jour. L’API renvoie les mêmes données :

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

Les conditions d’automatisation peuvent tester les données de plugin : une règle peut ainsi router une conversation selon le forfait du client dans votre système.

5. API de gestion

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. Manifeste

Un plugin publié se déclare dans un manifeste : nom, catégorie, portées demandées, événements auxquels il s’abonne, formulaire de paramètres, allowed_source_ips facultatif, recommended_rotation_days et son tarif s’il est payant. Le manifeste pilote l’écran de connexion et la vérification préalable à la publication d’un plugin communautaire dans le catalogue.

Limites et bonnes pratiques

• Corps entrant jusqu’à 5 MB ; sortant 1 MB par défaut.
• Les clés d’API de plugin sont limitées à 300 requêtes par minute ; les webhooks entrants à 120 par minute et par plugin.
• Des échecs d’envoi persistants font passer un plugin à l’état dégradé ; plus de la moitié d’envois en échec pendant une heure le met en pause et avertit les administrateurs du compte.
• Ne journalisez ni n’affichez jamais le secret de webhook. Renouvelez-le si vous soupçonnez une fuite ; grâce à la période de chevauchement, rien ne casse.