BloumeChat SDK

Appearance

Démarrage rapide ​

Ce guide construit progressivement un petit bot : connexion, réponse à !ping, embeds, accueil des nouveaux membres, activité (Rich Presence), puis gestion des erreurs et de la déconnexion. Chaque bloc de code propose un onglet JavaScript — voir aussi Utiliser le SDK en JavaScript pour le détail des différences.

1. Se connecter ​

ts
import { BloumeChat } from "bloumechat";

const client = new BloumeChat();

client.on("ready", () => {
  console.log(`Connecté en tant que ${client.user?.tagString}`);
  console.log(`Présent sur ${client.guilds.cache.size} serveur(s)`);
});

client.login(process.env.BOT_TOKEN!);
js
const { BloumeChat } = require("bloumechat");

const client = new BloumeChat();

client.on("ready", () => {
  console.log(`Connecté en tant que ${client.user?.tagString}`);
  console.log(`Présent sur ${client.guilds.cache.size} serveur(s)`);
});

client.login(process.env.BOT_TOKEN);

ready se déclenche une fois que le socket est connecté, le profil du bot chargé (client.user), et tous ses serveurs pré-chargés (client.guilds.cache) — c'est le premier moment sûr pour lire ces propriétés ou appeler des méthodes qui en dépendent. client.login() retourne une Promise<void> qui se résout au même moment que l'événement ready : vous pouvez donc soit écouter l'événement, soit await l'appel.

ts
await client.login(process.env.BOT_TOKEN!);
console.log("Le bot est prêt !"); // équivalent à écouter "ready"

Reconnexions

Si la connexion est coupée puis rétablie après le premier ready, le client émet reconnect (et non un second ready) — voir Événements.

2. Répondre à un message ​

ts
client.on("messageCreate", async (message) => {
  // Ignore les messages du bot lui-même (et des autres bots, si besoin)
  if (message.author.bot) return;

  if (message.content === "!ping") {
    await message.reply("🏓 Pong !");
  }

  if (message.content === "!avatar") {
    await message.channel.send({
      embeds: [
        {
          title: `Avatar de ${message.author.username}`,
          image: { url: message.author.avatar ?? "" },
          color: 0x5e72e4,
        },
      ],
    });
  }
});
js
client.on("messageCreate", async (message) => {
  // Ignore les messages du bot lui-même (et des autres bots, si besoin)
  if (message.author.bot) return;

  if (message.content === "!ping") {
    await message.reply("🏓 Pong !");
  }

  if (message.content === "!avatar") {
    await message.channel.send({
      embeds: [
        {
          title: `Avatar de ${message.author.username}`,
          image: { url: message.author.avatar || "" },
          color: 0x5e72e4,
        },
      ],
    });
  }
});

messageCreate (alias de message, les deux se déclenchent pour le même événement) reçoit un objet Message complet — message.content, message.author (un User), message.channel (un Channel). message.reply() envoie une réponse liée au message d'origine ; message.channel.send() envoie un message classique dans le même salon. Toujours filtrer message.author.bot en premier pour éviter qu'un bot ne réponde à lui-même ou déclenche une boucle avec un autre bot.

Chaque message trigger message et messageCreate

Si vous écoutez les deux événements avec des handlers distincts, votre logique s'exécutera deux fois pour le même message. N'en écoutez qu'un des deux.

3. Utiliser l'EmbedBuilder ​

Pour des embeds plus lisibles qu'un objet littéral, préférez l'EmbedBuilder fluent :

ts
import { EmbedBuilder } from "bloumechat";

const embed = new EmbedBuilder()
  .setTitle("Bienvenue !")
  .setDescription("Merci d'avoir rejoint le serveur 🎉")
  .setColor("#5e72e4")
  .setTimestamp();

await message.channel.send(embed);
js
const { EmbedBuilder } = require("bloumechat");

const embed = new EmbedBuilder()
  .setTitle("Bienvenue !")
  .setDescription("Merci d'avoir rejoint le serveur 🎉")
  .setColor("#5e72e4")
  .setTimestamp();

await message.channel.send(embed);

channel.send() (et client.sendMessage()) acceptent directement une instance d'EmbedBuilder, une chaîne, ou un objet { content?, embeds?, replyToId? } où embeds peut mélanger des EmbedBuilder et des objets bruts — voir la page EmbedBuilder pour la liste complète des méthodes set*.

4. Réagir à l'arrivée d'un membre ​

ts
client.on("guildMemberAdd", async (data) => {
  const guild = client.guilds.cache.get(data.serverPublicId);
  const channel = guild?.channels.find((c) => c.name === "général");
  await channel?.send(`Bienvenue <@${data.userPublicId}> !`);
});
js
client.on("guildMemberAdd", async (data) => {
  const guild = client.guilds.cache.get(data.serverPublicId);
  const channel = guild && guild.channels.find((c) => c.name === "général");
  if (channel) await channel.send(`Bienvenue <@${data.userPublicId}> !`);
});

client.guilds.cache est une Collection (une Map enrichie) indexée par l'ID public du serveur : .get() retourne undefined si le serveur n'est pas (ou plus) en cache — toujours vérifier avant d'utiliser le résultat, comme ci-dessus avec ?. / le test explicite. Le payload guildMemberAdd n'est pas encore typé finement (data: any) : data.serverPublicId et data.userPublicId sont les champs garantis par le serveur.

5. Définir une activité (Rich Presence) ​

ts
await client.setActivity({
  type: "playing",
  name: "avec le BloumeChat SDK",
});
js
await client.setActivity({
  type: "playing",
  name: "avec le BloumeChat SDK",
});

type accepte "using" | "browsing" | "listening" | "playing". Le nom est tronqué côté client à 128 caractères (details à 64) avant l'envoi — inutile de valider la longueur vous-même. Placez cet appel dans le handler ready pour que l'activité soit visible dès la connexion. Pour tout effacer, appelez client.setActivity(null).

6. Gérer les erreurs et la déconnexion ​

Un bot en production doit toujours écouter error (sinon Node.js peut planter sur un EventEmitter sans listener d'erreur dans certains cas) et journaliser les déconnexions :

ts
client.on("error", (error) => {
  console.error("Erreur de connexion :", error.message);
});

client.on("disconnect", (reason) => {
  console.warn(`Déconnecté : ${reason} — reconnexion automatique en cours…`);
});

client.on("reconnect", () => {
  console.log("Reconnecté !");
});
js
client.on("error", (error) => {
  console.error("Erreur de connexion :", error.message);
});

client.on("disconnect", (reason) => {
  console.warn(`Déconnecté : ${reason} — reconnexion automatique en cours…`);
});

client.on("reconnect", () => {
  console.log("Reconnecté !");
});

Vous n'avez rien d'autre à faire pour que la reconnexion fonctionne : le client retente indéfiniment avec un backoff progressif (1s → 30s max). Si votre process doit s'arrêter proprement (ex. redémarrage planifié), appelez client.destroy() pour fermer le socket et retirer tous les listeners avant de quitter.

ts
process.on("SIGINT", () => {
  client.destroy();
  process.exit(0);
});

Bot complet ​

ts
import { BloumeChat, EmbedBuilder } from "bloumechat";

const client = new BloumeChat();

client.on("ready", async () => {
  console.log(`Connecté en tant que ${client.user?.tagString}`);
  await client.setActivity({ type: "playing", name: "avec le BloumeChat SDK" });
});

client.on("messageCreate", async (message) => {
  if (message.author.bot) return;
  if (message.content === "!ping") {
    await message.reply("🏓 Pong !");
  }
});

client.on("guildMemberAdd", async (data) => {
  const guild = client.guilds.cache.get(data.serverPublicId);
  const channel = guild?.channels.find((c) => c.name === "général");
  await channel?.send(`Bienvenue <@${data.userPublicId}> !`);
});

client.on("error", (error) => console.error("Erreur :", error.message));

client.login(process.env.BOT_TOKEN!);
js
const { BloumeChat, EmbedBuilder } = require("bloumechat");

const client = new BloumeChat();

client.on("ready", async () => {
  console.log(`Connecté en tant que ${client.user?.tagString}`);
  await client.setActivity({ type: "playing", name: "avec le BloumeChat SDK" });
});

client.on("messageCreate", async (message) => {
  if (message.author.bot) return;
  if (message.content === "!ping") {
    await message.reply("🏓 Pong !");
  }
});

client.on("guildMemberAdd", async (data) => {
  const guild = client.guilds.cache.get(data.serverPublicId);
  const channel = guild && guild.channels.find((c) => c.name === "général");
  if (channel) await channel.send(`Bienvenue <@${data.userPublicId}> !`);
});

client.on("error", (error) => console.error("Erreur :", error.message));

client.login(process.env.BOT_TOKEN);

Prochaines étapes ​

  • Événements — la liste complète des events et leurs payloads typés.
  • Permissions — restreindre les commandes de modération avec le bitmask BigInt.
  • Référence API — plongez dans chaque méthode du client, des managers et des structures.
  • Exemples — des bots complets prêts à copier-coller (modération, webhooks, Rich Presence).

SDK publié sous licence ISC.

Copyright © Bloume SAS — BloumeChat