@komozu/react

Composants React pour Komozu, le chat des utilisateurs connectés de votre site ou de votre application. Le même chat que le script d’intégration, sans iframe.

npm install @komozu/react

Le chat en une ligne

KomozuChat a besoin de votre clé publique (tableau de bord → Clés API), d’un salon et du jeton du membre connecté. Aucune intégration à créer : l’apparence par défaut est la même partout, et chaque réglage est une prop.

import { KomozuChat } from '@komozu/react';
import '@komozu/react/fonts'; // facultatif : polices auto-hébergées du thème Komozu

<KomozuChat clientId="kz_live_…" channel="general" token={user?.komozuToken ?? null} />

Apparence par défaut : intégré dans la page, surface carte (card), hauteur auto (jusqu’à 600 px), la couleur du projet (Réglages du projet), clair ou sombre selon le système du visiteur (les visiteurs peuvent changer depuis le chat). Les images et vidéos suivent le réglage du salon.

Prop
`clientId`	Clé publique (`kz_live_…`), obligatoire
`channel`	Slug (ou UUID) du salon, ou `{ externalId: '…' }` pour un salon que votre serveur a créé avec cet identifiant. Obligatoire
`token`	Le jeton du membre connecté, conservé par votre serveur quand il a créé le membre (Identifier vos utilisateurs). Sans lui, ou à `null` après une déconnexion, le chat invite seulement à se connecter sur votre site : aucun message, aucun champ de saisie
`layout`	`inline` (par défaut, intégré dans la page) ou `floating` (bulle dans un coin en bas)
`surface`	`card` (par défaut, carte) ou `blend` (fondue dans votre page)
`primaryColor`	`#RRGGBB` ; par défaut : la couleur du projet (`null` = palette Komozu)
`themeMode`	`auto` (par défaut), `light`, `dark`
`height`	`auto` (par défaut) ou un nombre de pixels (mode intégré)
`maxHeight`	Hauteur maximale en mode `auto` (par défaut `600`)
`position`	`bottom-right` (par défaut) ou `bottom-left` (bulle)
`title`, `radius`	Titre du chat ; arrondi des coins `none`, `sm`, `md`, `lg`, `full`
`locale`	`en` ou `fr` ; par défaut : la langue du navigateur du visiteur
`tokenProvider`	Facultatif : une fonction qui renvoie le jeton (l’emporte sur `token`)
`apiUrl`	Par défaut `https://api.komozu.com`

Pas de jeton membre, salon inconnu, domaine refusé, salon privé, membre banni ou jeton refusé : le composant affiche un écran d’état court et sobre au lieu d’échouer en silence.

Messages épinglés et admins de salon

Rien à configurer : le chat affiche le dernier message épinglé en haut, et un bouton ouvre la liste des messages épinglés dans un panneau qui glisse à l’intérieur du chat (il tient dans une petite iframe et dans la bulle). Un clic sur un message épinglé ramène à la conversation et défile jusqu’à lui, en chargeant les messages plus anciens si besoin.

Quand le membre connecté est admin du salon (dashboard, ou channels.setRole), le chat affiche le badge Admin à côté de son nom et, dans le menu ⋯ de chaque message : épingler / désépingler, supprimer et retirer un membre (salons privés). Supprimer et retirer demandent une confirmation dessinée dans le chat. Un changement de rôle s’applique tout de suite au chat ouvert ; l’API vérifie chaque action.

Signaler un message

Chaque membre peut signaler un message depuis son menu ⋯ (tout message sauf les siens, ceux des admins compris). Une courte confirmation dessinée dans le chat propose un motif facultatif (spam, harcèlement, contenu choquant, autre) ; le chat remercie ensuite le lecteur et l’action devient « Signalé ». Le propriétaire du projet retrouve le message dans la page Signalements du tableau de bord et reçoit un email. Rien n’identifie qui l’a signalé.

Le bouton ⋯ est collé à chaque bulle (au survol, toujours visible sur écran tactile) et ouvre les actions du message juste en dessous : Modifier sur ses propres messages, Signaler et les actions d’admin. Modifier transforme la bulle en champ (Entrée enregistre, Maj+Entrée va à la ligne, Échap annule) ; un message modifié affiche « modifié » chez tout le monde. Un membre modifie ses propres messages sans limite de durée.

Un salon par événement

Votre serveur crée un salon par événement avec votre propre identifiant (@komozu/node), et chaque page d’événement affiche son salon :

<KomozuChat clientId="kz_live_…" channel={{ externalId: `evt_${event.id}` }} token={user.komozuToken} />

Le salon doit appartenir au projet de la clé ; son niveau d’accès et les domaines autorisés du projet s’appliquent comme d’habitude.

Une bulle à vos couleurs

<KomozuChat clientId="kz_live_…" channel="support" token={user.komozuToken} layout="floating" position="bottom-left" primaryColor="#047857" />

Langue

Les textes (boutons, statuts, erreurs) sont en anglais ou en français. Par défaut : la langue du navigateur du visiteur (français pour fr, fr-CA…, anglais sinon). Imposez-la avec locale="fr" sur KomozuChat ou KomozuProvider, ou entourez les composants autonomes de KomozuLocaleProvider. useKomozuMessages() renvoie les textes de la langue en cours.

Briques de plus bas niveau

import { KomozuProvider, ChatBox, ChatWidget } from '@komozu/react';

<KomozuProvider options={{ apiUrl: 'https://api.komozu.com', clientId: 'kz_live_…', memberToken: user?.komozuToken }} theme={{ surface: 'card' }} locale="fr">
  <ChatBox channelId="u15" height="auto" maxHeight={600} />      {/* intégré */}
  <ChatWidget channelId="u15" position="bottom-right" />          {/* bulle flottante */}
</KomozuProvider>

ChatBox est l’unique composant de chat utilisé par tous les modes (intégré card / blend, panneau flottant). Il affiche un seul salon ; showChannelSwitcher (false par défaut) liste les salons du projet accessibles en lecture, pour les applications qui naviguent entre plusieurs salons.
« Propulsé par komozu » suit l’offre du projet : toujours affiché sur Free, masqué sur Starter et Pro. Sur une offre payante, <ChatBox showPoweredBy /> le réaffiche ; sur Free, showPoweredBy={false} n’a aucun effet.
Hooks : useKomozu, useChannel, useMessages, useTyping, useChannels, useChannelLookup, useKomozuMessages, useChannelAdmin (rôle du lecteur, messages épinglés, actions d’admin), useMessageReport (Signaler : confirmation, motif, remerciement), useMessageEdit (modifier ses propres messages).
Éléments : MessageList / MessageItem (actions facultatives à côté de la bulle, editor à sa place), MessageInput, ChatHeader, ChatStatusScreen, AttachmentPreview, AuthorBadge (admin : admins du salon et propriétaire du projet), PinnedBanner, PinnedPanel, MessageActionMenu (le menu ⋯), MessageActions (Modifier, Signaler, plus les actions d’admin), MessageEditor, ChatConfirmDialog, ReportReasonPicker…
Thème : variables CSS --komozu-* sur la racine (KomozuThemeRoot), en clair et en sombre. Toute classe kz-* peut être restylée en CSS classique.

Aperçu sans serveur

@komozu/react/preview fait tourner le vrai chat sans réseau ni compte : historique d’exemple, un message épinglé, et ce que vous envoyez s’affiche seulement dans la page (rien n’est publié). Pratique pour les revues de design et les tests d’interface. Passez PREVIEW_MEMBER_TOKEN comme jeton membre : sans jeton, le chat invite seulement à se connecter.

import { KomozuProvider, ChatBox, MemoryStorage } from '@komozu/react';
import { createPreviewFetch, PREVIEW_MEMBER_TOKEN } from '@komozu/react/preview';

const options = {
  apiUrl: 'https://preview.komozu.local',
  clientId: 'preview',
  storage: new MemoryStorage(),
  memberToken: PREVIEW_MEMBER_TOKEN,
  fetch: createPreviewFetch({
    viewerName: 'Vous',
    live: [{ author: { member: 'Hibou' }, content: 'Il y a quelqu’un ?', delayMs: 3000 }],
  }),
};

<KomozuProvider options={options} locale="fr">
  <ChatBox channelId="general" />
</KomozuProvider>

Options de createPreviewFetch : history (messages déjà présents dans #general), live (messages qui arrivent après delayMs, chacun précédé de l’indicateur de saisie, joués une fois), attachmentsEnabled (true par défaut), viewerName (nom de vos propres messages, You par défaut).

Guides

Démarrer, Identifier vos utilisateurs, Intégration avancée
Client de base : @komozu/core · SDK serveur : @komozu/node