Développer des bots Sibrel

Créez votre premier bot

• Ouvrez Paramètres → Bots → Créer un bot. Votre hébergeur peut désactiver la création de bots.
• Choisissez un nom d’utilisateur en a-z0-9_, de 2 à 32 caractères. Enregistrez le jeton : il n’est affiché qu’une seule fois.
• Ajoutez le bot dans les paramètres de la communauté et accordez uniquement les permissions nécessaires. La gestion exige MANAGE_BOTS.
• Lancez le programme du bot sur votre machine ou votre serveur. Un compte bot n’exécute aucun code.
• Utilisez l’adresse d’API de l’hébergeur qui a émis le jeton.

Les bots agissent dans les salons des communautés qu’ils ont rejointes. L’API Bot ne prend pas en charge les messages directs ni les espaces publics.

Authentification et secrets

Authorization: Bearer <BOT_TOKEN>

Les actions de bot exigent un jeton de bot. Créer ou modifier un bot, l’ajouter à une communauté et définir ses permissions exigent le jeton de compte du propriétaire ou d’un administrateur. Séparez ces autorisations.

Stockez les jetons dans des variables d’environnement, jamais dans du code navigateur ni dans Git. La base de l’hébergeur stocke des empreintes de jetons. Révoquez tout jeton divulgué et émettez-en un nouveau. La passerelle transmet le jeton dans la chaîne de requête : masquez donc les URL dans les journaux des proxys inverses et de supervision. Utilisez HTTPS/WSS.

Exemple minimal fonctionnel

Nécessite Node.js 22+ avec fetch et WebSocket intégrés. Télécharger ping-bot.en.mjs. L’exemple enregistre /ping, répond dans un salon et se reconnecte après une coupure.

$env:SIBREL_API_URL = "https://api.example.org"
$env:SIBREL_BOT_TOKEN = "your-token"
node ./ping-bot.en.mjs

API REST du bot

POST /api/bots/messages
{
  "channel_id": 42,
  "content": "Bonjour depuis le bot !",
  "reply_to_id": 123
}

Envoi réussi : 201 { message }. N’envoyez pas Content-Type: application/json sans corps : une requête JSON vide peut renvoyer 400.

Gérer les bots et les permissions

Les bots ont leur propre masque de permissions par communauté, et non des rôles de membre ordinaires. Voir les salons : 16384 ; envoyer des messages : 32768 ; voix : 65536. Ces trois permissions donnent 114688. Les bots n’obtiennent aucun accès administrateur.

Commandes slash

PUT /api/bots/commands
{ "commands": [
  { "name": "ping", "description": "Check the bot response", "options": [] },
  { "name": "echo", "description": "Repeat text", "options": [
    { "name": "text", "description": "Your text", "type": "string", "required": true }
  ] }
] }

Noms : 1 à 32 caractères, a-z0-9_-. Jusqu’à 100 commandes et 10 options par commande. Types : string, number, boolean, user, channel, role ; jusqu’à 25 choices. Descriptions de commande : 200 caractères.

PUT remplace toute la liste : envoyez donc toujours l’ensemble complet. Dans message:create, une invocation détectée contient command: {bot_id, name, options, args}. Vérifiez bot_id pour ne pas répondre aux commandes d’un autre bot. Les commandes désactivées ou inconnues arrivent comme texte normal.

Choisir un membre, un salon ou un rôle

Les options de type user, channel et role se choisissent dans une liste avec recherche, sans les taper à la main. Le bot reçoit un jeton de mention plutôt qu’un nom : renommer un salon, un rôle ou un membre ne casse donc jamais une invocation déjà envoyée.

• La recherche porte sur le nom et, pour les membres, sur les pseudonymes et l’identifiant de connexion.
• Les mots de service fonctionnent aussi : « voice » trouve les salons vocaux, « role » les rôles, « text » les salons textuels.
• Les correspondances en début de nom passent devant les autres.
• Huit options au maximum sont affichées ; affinez la recherche si la vôtre manque.
• Entrée choisit la première option, les flèches déplacent la sélection, Échap vide la recherche, Retour arrière revient à la saisie normale.

La valeur arrive sous forme de jeton dans command.options ({ "user": "<@42>" }) et à la même position dans command.args. Un identifiant brut est aussi accepté, mais seul le jeton s’affiche comme mention dans le texte de réponse.

Passerelle et événements

wss://api.example.org/api/bots/gateway?token=<BOT_TOKEN>

{ "type": "ready", "bot_id": 7, "guilds": [1, 2] }
{ "type": "ping" }
{ "type": "pong" }

Événements : message:create, message:update, message:delete, reaction:add, reaction:remove, interaction. Les données des événements d’action se trouvent dans data ; ready porte bot_id et guilds au premier niveau.

La file de la connexion retient 256 messages. Un débordement produit message:drop ; des événements plus anciens peuvent être perdus. Prévoyez des reconnexions différées, la surveillance du pong et une restauration d’état via REST. Ne supposez pas une livraison exactement unique.

Boutons, embeds et interactions

{
  "channel_id": 42,
  "embeds": [{ "title": "Test", "description": "Appuyez sur le bouton", "color": 5793266 }],
  "components": [{ "type": 1, "components": [
    { "custom_id": "ping", "label": "Ping", "style": 1 }
  ] }]
}

Un bouton a un libellé allant jusqu’à 80 caractères et un custom_id unique jusqu’à 100. Les boutons lien utilisent une URL http/https au lieu d’un custom_id. Jusqu’à 5 rangées de 5 boutons, soit 25 au total. Styles 1 à 4 : primary, secondary, success, danger. disabled et emoji sont pris en charge.

{ "type": "interaction-reply", "nonce": "from the event",
  "action": "ephemeral", "content": "Pong !" }

Répondez dans les 3 secondes. ephemeral n’est visible que par la personne qui clique ; message publie dans le salon ; update modifie le message portant le bouton. Les réponses éphémères restent en mémoire jusqu’à 15 minutes et disparaissent au redémarrage ; ce n’est pas un stockage secret.

content : jusqu’à 2000 caractères ; jusqu’à 10 embeds pour 6000 caractères au total. Emoji personnalisés : <:name:id>. Voir aussi Webhooks pour des exemples d’embeds.

Voix

POST /api/bots/voice/join renvoie channel_id, identity et livekit. Si LiveKit est configuré, utilisez le token et livekitUrl renvoyés avec un SDK client compatible. Avec livekit: null, le bot n’apparaît que dans la liste des membres et ne transmet aucun audio. La requête REST ne lance aucune lecture à elle seule.

Erreurs et exploitation

Masquez les secrets dans les journaux, limitez l’accès aux variables d’environnement et ne répondez pas aux propres messages du bot. Coordonnez la collecte de données avec les administrateurs et les utilisateurs, et définissez la conservation et la suppression.

Salons vocaux pour les bots

Un bot disposant de la permission distincte CREATE_VOICE_CHANNELS peut créer des salons vocaux avec POST /api/bots/guilds/:guildId/channels. États : GET /api/bots/guilds/:guildId/voice-states. Demande de déplacement : POST /api/bots/guilds/:guildId/voice/move. Suppression d’un salon vide : DELETE /api/bots/channels/:channelId. L’hôte contrôle les permissions et limites ; un jeton seul ne donne pas ces droits.