Catalogue des événements

Structure de la charge utile

Chaque événement est un objet JSON :

{
  "id": "evt_01HKQN9…",
  "type": "conversation.created",
  "occurred_at": "2026-04-20T14:23:45.123Z",
  "account_id": "7c1d2c6e-…",
  "site_id": "0f3a…",
  "data": { … the resource, in the same shape the API returns it … }
}

id est la valeur de l’en-tête X-RolChat-Event-Id et reste identique d’une nouvelle tentative à l’autre. type suit la forme <domain>.<noun>.<verb> ou <domain>.<verb> en snake_case. data contient la ressource telle que la renverrait l’endpoint GET correspondant : un récepteur peut donc être écrit à partir de la référence de l’API sans jamais avoir besoin d’un second schéma.

Familles d’événements

Famille	Exemples	Émis lorsque
conversation.*	conversation.created, conversation.assigned, conversation.resolved, conversation.reopened, conversation.merged	Une conversation change d’état ou de responsable
message.*	message.created, message.delivered, message.read, message.failed	Un message est publié ou son statut de remise change
crm.*	crm.lead.created, crm.contact.created, crm.contact.updated, crm.contact.merged, crm.deal.stage_changed, crm.deal.won	Un prospect, un contact, une entreprise ou une opportunité change
ticket.*	ticket.created, ticket.status_changed, ticket.assigned, ticket.sla_breached	Un ticket change
visitor.*	visitor.identified, visitor.cobrowse.requested	Un visiteur est identifié ou demande une session de co-browsing
marketing.*	marketing.form.submitted, marketing.booking.created, marketing.campaign.sent, marketing.unsubscribed	Formulaires, réservations, campagnes
kb.*	kb.article.published, kb.article.unpublished	Changements dans la base de connaissances
phone.*	phone.call.started, phone.call.ended, phone.call.recorded, phone.call.transcribed, phone.voicemail.received	Appels et messagerie vocale
automation.*	automation.rule.executed, automation.rule.failed	Une règle d’automatisation s’exécute
privacy.*	privacy.consent.granted, privacy.consent.withdrawn, privacy.dsr.received	Consentement et demandes des personnes concernées
billing.*	billing.invoice.created, billing.trial_expiring, billing.subscription.changed	Abonnement et factures
auth.*	auth.api_key.created, auth.api_key.revoked, auth.account.swapped	Événements du compte liés à la sécurité
ai.*	ai.usage.recorded	Chaque appel à un adaptateur IA, avec le nombre de jetons

La liste exacte s’enrichit avec le produit ; l’écran d’abonnement affiche chaque type que votre compte peut recevoir et permet de filtrer par type.

S’abonner

Les abonnements aux webhooks appartiennent à un plugin. Dans Paramètres → Plugins, ouvrez le plugin (ou créez-en un personnalisé) et ajoutez un endpoint : URL HTTPS, types d’événements souhaités et, en option, une liste d’IP autorisées. Le secret de signature n’est affiché qu’une fois. Les envois, les nouvelles tentatives et les lettres mortes de cet endpoint apparaissent dans le Journal des webhooks du plugin.

Le Plugin Protocol, décrit sur la page Plugins, explique comment un plugin déclare dans son manifeste les événements dont il a besoin.

Ordre et remise

• La remise se fait au moins une fois. Dédoublonnez par id.
• Les événements d’une même ressource sont envoyés dans l’ordre, mais les nouvelles tentatives peuvent modifier l’ordre d’arrivée. Utilisez occurred_at et le updated_at de la ressource plutôt que l’heure d’arrivée.
• Un abonnement qui échoue sans cesse accumule des lettres mortes ; au-delà de 100 pour un même endpoint, une alerte est levée côté RolChat et un avertissement s’affiche dans le journal du plugin.