Bot/Automations API?

[mrmeloman]

Hello!
I'm slowly getting my community ready to migrate to Nodyx, I'm about to set up an instance in ~2 weeks and check it out with a group of testers. We're migrating from the Discord server where we have our own bot/mascot. It comes with various additional mechanics - earning exp for certain activity, playing sets of audios/videos in voice chats, managing some non-standard text channel logic, calculating some advanced activity metrics, etc, etc.

Is there a chance we can have something like that for our Nodyx instance? Something that can have access to message history, message events in text chats, activity in voice chats, etc. - and react accordingly, by posting something, playing something in the voice chat, moderating the community and stuff like that? It would be ideal to have a python library for such bits, but even the existing of the API would be great, I might just publish the library myself in that case.

[Pokled]

Hey, thanks for the heads-up about your migration plan, this is exactly the kind of use case we want to support.

Short answer: a bot/automation API is on the roadmap and aligned with Nodyx's vision (self-hosted, open). It's not shipped today, but a moderation-focused "Bot API v1" is reasonable to land in the next few weeks. Voice bots will take longer for architectural reasons (more below).

What's realistic short-term (Bot API v1, moderation + chat)

Most of the plumbing already exists:

• REST API at /api/v1/* already covers the moderation actions (delete message, mute, kick, ban, warn, list users, read message history).
• Socket.IO already streams chat events in real time, so a bot can subscribe and react instantly.

What's missing and what we'd add:

• A dedicated bot account type with a long-lived token (regular user tokens expire after 7 days, that's annoying for bots).
• A scoped bot role so a bot can moderate without holding full admin keys.
• Minimal Python SDK (~200 lines: connect to Socket.IO, call REST). I'd rather ship a tiny solid wrapper than a heavyweight framework, and let the community grow it.

With that, your bot can do: auto-delete on banned words, anti-flood, anti-spam links, warn/kick on N strikes, custom commands (!rules, !faq), scheduled posts, channel locks by time, etc.

What you can already build on your side

XP, leveling, leaderboards, advanced activity metrics: this logic lives in the bot itself. It listens to chat events and writes to its own local DB (SQLite is enough). Nodyx doesn't need to know, so this isn't blocked by us at all. Same for "non-standard text channel logic", once the bot has read+write access, custom flows are yours to design.

What's harder and why (voice bots)

Voice in Nodyx is WebRTC peer-to-peer mesh, not a centralized voice server. There's no shared audio stream a bot can simply hook into. A Python voice bot would need to act as a real WebRTC peer (e.g. via aiortc), which is roughly 10x the work of the moderation bot. We want to support this eventually but I'd be honest: it's a phase 2, not a "few weeks" thing.

Timing

Your migration is in ~2 weeks, the Bot API v1 won't be ready in that window. Two pragmatic paths:

1. Migrate the community first, run without the bot for a short period (only the bot is missing, the rest of the platform is ready).
2. Use the existing admin REST endpoints with a temporary admin token to script basic moderation now (rough, but works). We can help you scope what's safe.

If you're up for it, I'd love your input on the Bot API v1 spec. You've clearly thought about what a community bot needs to do, and that kind of feedback shapes a better API. I'll open a tracking issue ("RFC: Bot API v1") and ping you, sounds good?

[mrmeloman]

It's not so much about moderation, to be honest - the bot mostly generates engagement and things like that. I've seen that Nodyx has moderation tools, and I'm okay with using them if needed (although they are not needed that much at the moment). Since it's a small test group going in in 2 weeks, not the whole community, it's okay to wait for some time. Full migration will be later, after we are sure that the tool is right.
REST handles are okay for now, especially if we will have persistent tokens in the near future. Some form of bot API, even just for text stuff, is even better. Thanks for the clarification!

[Pokled]

Quick follow-up: I just opened PR #26 with a full spec for OctoGuard, a native moderation bot for Nodyx that came directly out of this thread.

👉 #26

It's a Phase 1 spec only (no implementation yet), covering auto-mod, welcome, custom commands, logs with undo, and an optional outbound webhook. Phase 2 will add XP/leveling/leaderboard, Phase 4 will add the external Bot API + WebRTC voice bot (your custom Python logic + voice mascot lands there).

I'd love your eyes on the PR description, especially:

• whether the Phase 1 module set covers what you need short-term
• whether the Phase 4 plan (external API + voice via aiortc) matches what you had in mind
• any auto-mod rule type you've used in your Discord bot that I missed

No pressure on timing, your input would just genuinely shape a better v1.

[mrmeloman]

To clarify: I don't expect Nodyx to develop the bot features I need (exp, levelling, voice actions, etc.). I just want an external API so I can develop my own tool and fine-tune it for my community over time. This was the case for the last ~4-5 years with our Discord bot, and I like this path.

Furthermore, standard implementations are not always the best for a specific community. An example: usually, exp systems reward users for sending messages to chats. In my case, I shifted towards rewarding users when someone replies to their messages - so it's not just a "type anything" kind of reward, but a "be someone who people want to talk to" reward. This logic was achieved gradually over the years and will, undoubtedly, shift in the future, along with our community changing.

You're the boss, but I would love to see time, effort and tokens being channelled towards making it easier to develop our own bot than to try to adapt the tool to the specific needs of every community.

[yudin-s]

For the migration use case, I would keep two tracks separate:

1. native moderation bot, like OctoGuard
2. external bot API for community-specific logic

OctoGuard can cover the common baseline, but the Discord-style custom bot/mascot use case needs an external API contract. Otherwise every community-specific workflow eventually becomes a feature request against core.

For Bot API v1, the minimum useful surface is probably:

Events:
- message.created
- message.updated
- message.deleted
- member.joined
- member.left
- member.timeout/ban/kick
- voice.session.started/ended, if available as metadata

Actions:
- send message
- delete message
- warn/mute/kick/ban
- read recent message history with pagination
- create audit log entry / moderation note

The security model matters more than SDK size:

bot account
  -> long-lived token
  -> scoped permissions
  -> per-channel allow/deny
  -> rate limits
  -> audit log for every mutating action

For event delivery, Socket.IO is fine initially, but I would include event IDs from day one:

{
  "event_id": "...",
  "type": "message.created",
  "created_at": "...",
  "data": {}
}

That lets bot authors build idempotency and reconnect handling. Without event IDs, XP/leveling and moderation counters become fragile after reconnects.

Voice bots can stay phase 2/4. A good interim design is to expose voice presence/activity metadata first, but not audio. That still unlocks a lot of bot logic: XP for voice participation, moderation alerts, room occupancy rules, and scheduled announcements in text when a voice event happens.

For the Python SDK, I would keep it thin:

@bot.on("message.created")
async def handle_message(event):
    ...

await bot.send_message(channel_id, "...")
await bot.warn(user_id, reason="...")

The SDK should mostly be typed wrappers around the stable REST + event contract, not a framework that hides the protocol too early.

[mrmeloman]

Yeah, this. This is exactly what I wanted to ask for.

[yudin-s]

This is a strong Phase 1.

The part I would keep especially careful now is the transition from native OctoGuard events to the future external Bot API. If the internal audit/event model is designed as if it might later become public, Phase 4 will be much easier.

For example, I would try to keep every OctoGuard audit event close to a future bot event envelope:

{
  "event_id": "...",
  "type": "octoguard.message.flagged",
  "created_at": "...",
  "community_id": "...",
  "channel_id": "...",
  "actor": {
    "type": "system",
    "id": "octoguard"
  },
  "target": {
    "type": "message",
    "id": "..."
  },
  "policy": {
    "rule_id": "...",
    "mode": "report_only",
    "action": "warn"
  }
}

Even if external bots cannot consume this yet, it gives you a stable internal vocabulary:

• event id
• event type
• actor
• target
• policy/rule metadata
• report_only vs enforced action

Then Bot API v1 can reuse the same envelope instead of inventing a second event language later.

For the temporary admin-token path, I would keep it very explicit in docs as a migration bridge, not the recommended long-term integration path. Something like:

Temporary automation mode:
- use a dedicated low-privilege admin account
- restrict it to the minimum channels/actions
- rotate the token before/after the migration test
- prefer report/log actions over destructive actions

That gives early adopters a path without normalizing “bots are just admins with scripts”.

Nice progress. The fact that Phase 1 landed with event IDs and webhook isolation already removes a lot of future pain.

[Pokled]

Hey @yudin-s, first a real thank you. This isn't the kind of comment you toss off in 30 seconds. You clearly thought hard about it. Pointing out event_ids from day one, the voice-metadata-without-audio middle path, and the per-channel scoped security model gave me three things I can actually integrate. That's a gift, not just feedback.

And @mrmeloman, thank you too. You're the reason this whole thread started, and the reason the OctoGuard spec exists in the first place.

I want to be honest with both of you about where Nodyx is right now. It's a solo project. One person, working on it with care, and I won't pretend otherwise. So when I read your needs I see them clearly: a community to protect, real-world timelines, an existing bot setup that has to keep running. Those needs are legitimate, real, valid. None of this is a "nice to have", I get it.

What I can commit to honestly:

• Your input goes into priorities. Event IDs will be in the OctoGuard Phase 1 logs and in the Bot API v1 design from day one. Voice metadata without audio is going to slot in as a Phase 3 intermediate step. That's a much smarter path than jumping straight to WebRTC voice peers, and I would have missed it without you.
• The security model you outlined (long-lived token, scoped per-channel perms, rate limits, full audit log) is already what's planned for Phase 4. I'll annotate the spec to make it explicit.

What I won't do:

• I won't promise dates I can't keep. The Bot API v1 is weeks of careful work. I would rather under-promise and over-deliver than oversell and disappear on you.

I also want to say something broader. Nodyx isn't trying to race anyone. It's not trying to be a "better Discord" or replace any particular platform. The goal is a free community hub, no dark patterns, no growth hacking, no engagement traps. A project like that moves slower than VC-backed ones, and that's a feature, not a bug. So I'm asking for patience. Not because your needs should wait quietly, but because I would rather build this well with you than sprint and ship something brittle that breaks under you.

Every request raised here is welcome. Every idea is legitimate. The thread stays open, your voices shape the spec. Just bear with me. There is only one of me on this side of the screen, and I want to do this right.

Thank you, both of you.

[Pokled]

Je ferai tout ce qui est en mon pouvoir pour mettre en place votre demande. Mais elle ne pourra pas être honorée en si peu de temps. Sachez que je ferai tout pour répondre à votre satisfaction, dans les limites de mes moyens. Votre demande devient une priorité car je la respecte. Mais oui… mais : « Qui ose gagne1 , croche et tient2 ». Soyons honnêtes : je ne pourrai pas vous donner cela sans votre aide pendant le développement. Je compte sur vous !
Deepl trad (répondu avec le coeur )

*1 => pourquoi pas , et on fera plus
*2 => quoi qu'il arrive , on doit y arriver.

==============================

Deepl (❤️)

I will do everything in my power to fulfill your request. However, it cannot be completed in such a short time. Please know that I will do my best to meet your expectations, within the limits of my capabilities. Your request is a priority because I take it seriously. But yes… but: “He who dares wins1, seizes, and holds on2.” Let’s be honest: I won’t be able to deliver this without your help during development. I’m counting on you!
Deepl Translate (answered from the heart)

*1 => why not, and we’ll do more
*2 => no matter what happens, we have to make it happen.

[Pokled]

Quick update

OctoGuard Phase 1 is now merged on main and deployed on nodyx.org (kill-switch off, rule table empty, so zero impact on members for now). Progressive rollout starts this week: 1 rule in report_only mode → observe → enable.

Full announcement (in French) with the philosophy + module list: https://nodyx.org/forum/annonces/octoguard-la-moderation-automatique-ethique-et-sur-mesure-pour-nodyx-44997e42

What landed in Phase 1 (native, in-core moderation):

• Auto-mod pipeline with 5 matcher types (substring, word, regex, link, emoji-flood), ReDoS protection via re2 + safe-regex heuristic
• 6 actions: delete, warn, mute_timed, kick, ban, report_only
• Welcome message (public, via a ghost OctoGuard bot user) + optional auto-grade on join
• Custom commands (!rules, !discord, ...) with Redis-backed per-channel cooldown
• Reports queue (anti-abuse: rate limit per reporter + cooldown per target)
• Audit log filtered on octoguard.* with event IDs (your point, @yudin-s, baked in from day one)
• Outbound HMAC-SHA256 webhook, queued in Redis, fire-and-forget worker (the chat pipeline never pays the webhook latency)
• Full admin UI (8 tabs) at /admin/octoguard

What this is not yet:

• Not the external Bot API. This is the native in-core baseline (the "OctoGuard track"). The external Bot API + Python SDK + voice-presence-without-audio (your phase 3 intermediate, @yudin-s) is still Phase 4 of the roadmap. Honest timing: not weeks, more like a couple of months once Phase 1 has soaked.

@mrmeloman, if your migration timeline still holds, the realistic path is: spin up your instance, use OctoGuard for the moderation baseline, and run your custom Discord-bot logic in parallel against a temporary admin token until Phase 4 lands. I'll help you scope what's safe.

Thanks again to both of you, the spec is genuinely better because of your input.