Référence

Référence : @zean-chat/react

Le composant ZeanChat et le hook useZean, pour Next.js, React Router, TanStack Start et React.

Mis à jour le 18 octobre 2026

Les exemples affichent app_your_app_key. Ouvrez ce guide depuis Paramètres de l’App > Développeurs > Démarrage pour y voir la clé de votre App.

Installez le paquet, puis affichez ZeanChat une seule fois, dans ce qui enveloppe toutes vos pages. Voir Installer le chat sur un site React.

Terminal

npm install @zean-chat/react

Exports

Nom	Type	Description
`ZeanChat`	`(props: ZeanChatProps) => null`	Affiche le chat. Il ne rend rien lui-même : le chat vit dans son propre cadre et reste ouvert d’une page à l’autre.
`useZean()`	`() => ZeanControls`	Ouvre et ferme le chat, et suit le nombre de réponses non lues. Marche dans n’importe quel composant, avant le chargement du chat.
`ZeanChatProps`	`interface`	Les props de `ZeanChat`.
`ZeanControls`	`interface`	Ce que renvoie `useZean()`.
`ZeanUser`	`interface`	La personne connectée, plus bas.
`ZeanAttributes`	`Record<string, ZeanAttributeValue>`	Les attributs du Contact : `{ city: "Douala", orders: 12 }`.
`ZeanLocale`	`'fr' \| 'en'`	Une langue du chat.

Props de ZeanChat

Nom	Type	Description
`appKey`	`string`	Obligatoire. La clé publique de l’App, dans Paramètres de l’App > Développeurs > Démarrage.
`user`	`ZeanUser`	Facultatif. Tant qu’une personne est connectée : `{ id, name, email }`. Laissez-le de côté quand personne ne l’est : une personne qui était connectée est déconnectée. Laissé de côté pendant que votre application charge encore la personne, il ne déconnecte personne. Les mêmes valeurs à chaque rendu ne changent rien. Voir Identifier vos Contacts.
`attributes`	`ZeanAttributes`	Facultatif. Ce que vous savez de la personne, montré sur la fiche du Contact. Envoyé de nouveau à chaque changement. Voir Attributs personnalisés.
`locale`	`'fr' \| 'en'`	Facultatif. La langue du chat. Sans elle : celle du navigateur si le chat la parle, sinon la langue par défaut de l’App. Lue au chargement de la page.
`tabAlert`	`boolean`	Facultatif. L’alerte d’onglet : tant que le Contact a des réponses à lire, le titre de votre onglet commence par leur nombre et son icône prend un point rouge. Active par défaut ; `false` la désactive. Voir Afficher le nombre de messages non lus.

JSX

<ZeanChat  appKey="app_your_app_key"  locale="fr"  user={user ? { id: user.id, name: user.name, email: user.email } : undefined}  attributes={{ plan: "pro", orders: 12 }}/>

useZean()

Nom	Type	Description
`open()`	`() => void`	Ouvre le chat.
`close()`	`() => void`	Ferme le chat.
`toggle()`	`() => void`	Ouvre le chat s’il est fermé, le ferme sinon.
`identify()`	`(user: ZeanUser) => void`	La personne s’est connectée. Le premier appareil qui donne son ID rejoint sa Conversation tout de suite ; un autre lui demande d’abord un code envoyé par email. Voir Identifier vos Contacts.
`signOut()`	`() => void`	La personne s’est déconnectée : le chat repart de zéro, anonyme.
`setAttributes()`	`(attributes: ZeanAttributes) => void`	Ajoute ces attributs à ceux déjà envoyés. Les valeurs refusées sont signalées dans la console. Voir Attributs personnalisés.
`unreadCount`	`number`	Le nombre de réponses que le Contact n’a pas lues, mis à jour à chaque changement. 0 côté serveur.

JSX

import { useZean } from "@zean-chat/react";export function HelpButton() {  const { open, unreadCount } = useZean();  return <button onClick={open}>Aide ({unreadCount})</button>;}

ZeanUser

Nom	Type	Description
`id`	`string \| number`	Obligatoire. Votre propre ID pour la personne, en texte ou en nombre, 200 caractères au plus. Le même ID sur votre site et dans votre application mobile donne une seule personne.
`name`	`string`	Facultatif. Son nom, sur sa fiche Contact.
`email`	`string`	Facultatif. Le code qui ajoute un autre appareil part à cette adresse : sans elle, un deuxième appareil ne peut jamais rejoindre le Contact.
`phone`	`string`	Facultatif. Son téléphone, sur sa fiche Contact.
`language`	`string`	Facultatif. Sa langue, n’importe laquelle, en code comme `pt` ou `pt-BR`. Sans elle, celle de son appareil est gardée. Elle ne change pas la langue du chat.

Le paquet porte la directive « use client » : avec Next.js, ZeanChat se place dans le layout racine sans autre réglage.