Créer un bot Onde
Un bot est un compte spécial piloté par ton programme. Il rejoint des espaces, lit les messages des fils qu'il peut voir et répond automatiquement : commandes, jeux, modération, annonces…
1. Crée une application
Dans Mes applications, clique sur Nouvelle application. Copie le jeton affiché : il ne sera plus jamais montré (tu pourras en régénérer un). Ce jeton est le mot de passe de ton bot : ne le partage jamais.
2. Ajoute le bot à un espace
Sur la fiche de l'application, utilise Ajouter à un espace, ou partage le lien d'ajout : toute personne ayant la permission « Gérer l'espace » pourra l'ajouter (si l'application est publique).
3. Lance ton code
Télécharge le SDK onde.js et l'exemple de bot (Node.js 22 ou plus récent), place-les dans un même dossier puis :
Sous Windows (PowerShell) : $env:ONDE_TOKEN="ton-jeton"; $env:ONDE_URL=""; node exemple-bot.js
SDK JavaScript
| Méthode | Description |
|---|---|
bot.send(channelId, texte) | Envoie un message dans un fil |
msg.reply(texte) | Répond dans le fil du message |
bot.edit(messageId, texte) | Modifie un message du bot |
bot.delete(messageId) | Supprime un message (le sien, ou un autre avec « Gérer les messages ») |
bot.spaces() | Liste des espaces du bot |
bot.space(id) | Détails d'un espace : fils, rôles, membres |
bot.history(channelId, { before, limit }) | Historique d'un fil (100 messages max par appel) |
bot.kick(spaceId, userId) / bot.ban(spaceId, userId, motif) | Modération (nécessite les permissions) |
bot.addRole(spaceId, userId, roleId) / bot.removeRole(...) | Gestion des rôles (nécessite « Gérer les rôles ») |
bot.api(méthode, chemin, corps) | Appel direct de n'importe quelle route REST |
Événements : ready, message, messageUpdate, messageDelete, memberJoin, memberLeave, spaceAdded, spaceRemoved, raw (tous les événements bruts), error, disconnect. La reconnexion est automatique.
Passerelle temps réel
Connexion WebSocket : /ws?bot=TON_JETON. Chaque événement est un objet JSON avec un champ t.
| Événement | Contenu |
|---|---|
hello | { sid, user } — connexion établie |
message:new | { serverId, message } — nouveau message dans un fil visible |
message:update | { serverId, message } |
message:delete | { serverId, channelId, messageId } |
member:join / member:leave | { serverId, member } / { serverId, userId } |
space:added / space:removed | Le bot a été ajouté à / retiré d'un espace |
space:refresh | Rôles, fils ou réglages modifiés : recharge l'espace |
channel:delete, presence, typing, voice:update | Autres événements de l'espace |
La connexion est fermée avec le code 4001 si le jeton est invalide (ou régénéré) et 4003 si le bot est désactivé.
API REST
Base : /api. En-tête obligatoire : Authorization: Bot TON_JETON. Corps et réponses en JSON. Les erreurs renvoient { "error": "..." }.
| Route | Description | |
|---|---|---|
| GET | /servers | Espaces du bot |
| GET | /servers/:id | Espace : fils, rôles, membres, permissions du bot |
| GET | /channels/:id/messages?before=&limit= | Historique d'un fil |
| POST | /channels/:id/messages | { content } — envoyer (2000 caractères max) |
| PATCH | /messages/:id | { content } — modifier un message du bot |
| DELETE | /messages/:id | Supprimer un message |
| GET | /users/:id | Profil public d'un utilisateur |
| PUT / DELETE | /servers/:id/members/:userId/roles/:roleId | Attribuer / retirer un rôle |
| DELETE | /servers/:id/members/:userId | Expulser |
| POST | /servers/:id/bans | { userId, reason } — bannir |
| POST | /servers/:id/leave | Quitter un espace |
Limite : 10 messages par tranche de 5 secondes. Au-delà, l'API répond 429.
Permissions
Un bot a les permissions de ses rôles dans chaque espace, comme un membre. Le champ me.perms de GET /servers/:id est un masque de bits :
| Bit | Valeur | Permission |
|---|
Règles
Les bots doivent respecter les mêmes règles que les membres. Pas de spam, pas de collecte de données personnelles, pas d'usurpation. Le staff d'Onde peut désactiver un bot à tout moment.