Référence de l'API serveur

Votre serveur pilote Komozu avec la clé secrète : membres, salons (un par événement ou par groupe), membres des salons privés, admins de salon, messages épinglés, modération, messages signalés. Le SDK @komozu/node couvre toutes les routes ci-dessous ; cette page est la référence HTTP.

Authentification et limites

Authorization: Bearer kz_sec_…

• Clé absente ou inconnue → 401 INVALID_SECRET_KEY.
• Toute requête portant un en-tête Origin (c’est-à-dire venant d’un navigateur) → 403 SECRET_KEY_IN_BROWSER. La clé secrète ne va jamais dans un navigateur ni dans une application mobile.
• Limitation de débit par projet : RATE_LIMIT_SERVER_PER_MINUTE (600 requêtes par minute par défaut). Au-delà → 429 RATE_LIMIT_EXCEEDED avec RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset et Retry-After.
• Les domaines autorisés ne s’appliquent pas à l’API serveur.
• Les erreurs sont en JSON { code, error, message } avec un code stable. Entrée invalide → 400 VALIDATION_ERROR.

Identifiants

• Les membres sont identifiés par leur identifiant externe : l’identifiant de l’utilisateur dans votre propre base de données (1 à 128 caractères).
• Les salons (segment :channel) par slug ou UUID, ou par leur externalId quand la requête porte ?by=externalId (jamais deviné : un identifiant externe pourrait ressembler au slug d’un autre salon). Avec @komozu/node, passez { externalId: 'evt_1102' }.
• Le slug est généré à partir du nom à la création (Tournament – Nov 2 → tournament-nov-2, puis -2, -3… s’il est déjà pris) et ne change jamais. externalId est facultatif, unique dans le projet et non modifiable.

Membres

Méthode et chemin	Corps / paramètres	Réponse	Erreurs
PUT /v1/server/members/:externalId	{ name (1–64), avatarUrl?: https:// URL | null }	201 créé / 200 mis à jour, { member, token }	400
PATCH /v1/server/members/:externalId	{ name?, avatarUrl? }	200 { member }	400, 404 MEMBER_NOT_FOUND
GET /v1/server/members/:externalId	—	200 { member }	404
GET /v1/server/members	?limit=1..100 (50)&cursor=&search=	200 { members, nextCursor }	400
DELETE /v1/server/members/:externalId	?deleteMessages=true|false (false)	200 { success }	404
POST /v1/server/members/:externalId/ban	{ reason?: string ≤ 500 }	201 { ban } (200 si déjà banni)	404
DELETE /v1/server/members/:externalId/ban	—	200 { success } (idempotent)	404 membre
POST /v1/server/members/:externalId/revoke-tokens	—	200 { token } (nouveau jeton)	404 MEMBER_NOT_FOUND

member = { externalId, displayName, avatarUrl, createdAt, updatedAt, lastSeenAt, banned }. La liste des membres est triée par identifiant externe ; nextCursor est le dernier identifiant externe de la page. search cherche dans le nom ou l’identifiant.

Quand PUT ou PATCH change le nom ou l’avatar d’un membre existant, les chats ouverts du projet mettent à jour les messages de ce membre tout de suite (member.updated), sans rechargement.

token est le jeton du membre pour le chat : il n’expire pas, conservez-le avec l’utilisateur et écrivez-le dans vos pages (Identifier vos utilisateurs). PUT renvoie un nouveau jeton valide à chaque appel (les précédents continuent de fonctionner jusqu’à ce que vous appeliez revoke-tokens). revoke-tokens refuse tous les jetons émis avant lui (401 TOKEN_REVOKED dans le chat), déconnecte les chats ouverts du membre et renvoie un nouveau jeton.

Salons

Méthode et chemin	Corps / paramètres	Réponse	Erreurs
POST /v1/server/channels	{ name (1–255), access?: 'members' | 'private' = 'members', externalId?, attachmentsEnabled?: boolean = true }	201 { channel } (slug généré)	400, 403 CHANNEL_LIMIT_EXCEEDED, 409 CHANNEL_EXTERNAL_ID_TAKEN
GET /v1/server/channels	—	200 { channels }
GET /v1/server/channels/:channel	?by=externalId	200 { channel }	404 CHANNEL_NOT_FOUND
PATCH /v1/server/channels/:channel	{ name?, access?, attachmentsEnabled? } (slug non modifiable)	200 { channel }	400, 404
DELETE /v1/server/channels/:channel	—	200 { success }	404
GET /v1/server/channels/:channel/members	—	200 { members } (chacun avec son role)	404
PUT /v1/server/channels/:channel/members	{ memberIds: string[1..100] }	200 { success } (idempotent)	404 MEMBER_NOT_FOUND (tout ou rien, liste les identifiants inconnus), 404 salon
DELETE /v1/server/channels/:channel/members	{ memberIds: string[1..100] }	200 { success } (idempotent)	404 salon
PUT /v1/server/channels/:channel/members/:externalId/role	{ role: 'user' | 'admin' }	200 { member }	400, 404 MEMBER_NOT_FOUND, 404 salon
GET /v1/server/channels/:channel/messages	?limit=1..100 (50)&cursor=	200 { messages, nextCursor }	404 salon
GET /v1/server/channels/:channel/pins	—	200 { messages } (le dernier épinglé en premier, 50 au maximum)	404 salon

channel = { id, slug, name, access, externalId, attachmentsEnabled, createdAt, updatedAt }. Niveaux d’accès : members (tout membre du projet) ou private (uniquement les membres ajoutés au salon). Lire et écrire demandent toujours un jeton membre : il n’existe pas d’accès anonyme. attachmentsEnabled: false désactive les images et vidéos dans le salon (le chat masque le bouton ; les envois de fichiers sont refusés avec 403 ATTACHMENTS_DISABLED).

message = { id, channelId, content, authorType, member, owner, authorRole, attachments, pinnedAt, editedAt, createdAt }. authorType vaut member ou owner (le propriétaire du projet, qui écrit depuis le dashboard ; owner vaut { displayName }). member vaut null pour un membre supprimé. authorRole est le rôle de l’auteur dans le salon : admin (propriétaire compris), user, ou null pour un membre supprimé. pinnedAt vaut null sauf si le message est épinglé ; editedAt vaut null sauf si son auteur l’a modifié (message.updated dans le chat).

Admins de salon

Un membre d’un salon est user (par défaut) ou admin. Dans le chat, un admin supprime n’importe quel message, épingle et désépingle et retire un membre d’un salon privé, sur ce salon uniquement. Bannir de tout le projet reste votre décision (API serveur, dashboard).

• Sur un salon privé, admin ajoute le membre au salon si besoin ; user lui laisse son accès.
• Sur un salon members, le rôle n’ajoute que des droits, jamais d’accès : GET …/members ne liste que les admins, et user retire la ligne de l’admin.
• Les chats ouverts appliquent le changement tout de suite (member.role_changed), sans reconnexion.

Modération

Méthode et chemin	Corps	Réponse	Erreurs
DELETE /v1/server/messages/:messageId	—	200 { success }	404 MESSAGE_NOT_FOUND (limité au projet)
PUT /v1/server/messages/:messageId/pin	—	200 { message } (idempotent)	404 MESSAGE_NOT_FOUND, 409 PIN_LIMIT_EXCEEDED (50 par salon)
DELETE /v1/server/messages/:messageId/pin	—	200 { message } (idempotent)	404 MESSAGE_NOT_FOUND

Signalements

Les membres peuvent signaler un message depuis le chat (bouton Signaler, motif facultatif : spam, harassment, inappropriate, other). Les signalements attendent ici, et dans la page Signalements du tableau de bord, jusqu’à ce que vous agissiez.

Méthode et chemin	Corps	Réponse	Erreurs
GET /v1/server/reports	—	200 { reports } (signalements ouverts regroupés par message, le plus récemment signalé en premier, 100 messages au maximum)
POST /v1/server/reports/:messageId/dismiss	—	200 { dismissed } (nombre de signalements classés ; le message reste)	404 REPORT_NOT_FOUND (aucun signalement ouvert pour ce message dans le projet)

report = { message, channel: { id, slug, name }, reportCount, reasons, firstReportedAt, lastReportedAt }. reasons compte les signalements par motif ({ spam: 2 } ; un signalement sans motif ne compte que dans reportCount). Rien n’identifie qui a signalé : ni identifiant de membre, ni adresse IP.

Pour agir sur un message signalé : DELETE /v1/server/messages/:messageId (ses signalements disparaissent avec lui), POST /v1/server/members/:externalId/ban pour son auteur (puis classez, ou supprimez le message), ou …/dismiss pour garder le message.

Effets de bord

• Supprimer un membre : ses messages sont conservés et affichés comme « Deleted member » (« Membre supprimé » en français), ou supprimés avec deleteMessages=true (message.deleted est envoyé pour chacun, les fichiers sont purgés). Ses chats ouverts sont déconnectés.
• Bannir un membre : il ne peut plus lire ni écrire dans aucun salon du projet jusqu’à la levée du bannissement ; ses chats ouverts sont déconnectés (access.revoked).
• Retirer un membre d’un salon privé : son chat ouvert sur ce salon est déconnecté.
• Changer l’accès d’un salon / supprimer un salon : chaque chat ouvert sur ce salon revérifie son accès (la suppression retire les messages, les intégrations, les membres du salon et les fichiers).
• Supprimer un message : il disparaît en direct pour tout le monde (épinglé ou non) ; ses fichiers et ses signalements sont supprimés.
• Épingler / désépingler : tous les lecteurs le voient en direct (message.pinned / message.unpinned).
• Changer un rôle : les chats ouverts affichent ou masquent aussitôt les actions d’admin et les badges (member.role_changed).
• Signaler un message (chat) : le propriétaire du projet reçoit un email (un au plus toutes les 15 minutes par projet). Un même membre qui signale de nouveau le même message dans les 24 heures ne compte qu’une fois. Un message classé ne revient que si quelqu’un le signale de nouveau.

Exemple : un salon par événement

const channel = await komozu.channels.create({ name: 'Tournament – Nov 2', externalId: `evt_${event.id}` });

Ensuite, sur la page de l’événement, @komozu/react l’affiche avec <KomozuChat clientId="kz_live_…" channel={{ externalId: 'evt_1102' }} />. Sans React, créez une intégration par salon dans le tableau de bord.