Skip to content

comms

Writing a bot that reads a Discord channel should not put a Discord SDK in your dependency graph, and supporting Slack later should not mean a second code path.

This module is the contract. Providers live in their own modules and register themselves, so your code depends on an interface and never on a gateway client.

c, _ := comms.NewClient(ctx, "discord", comms.ClientConfig{
    Token: tok,
    Needs: []comms.Need{comms.NeedMessages},
})
defer c.Close()

p, _ := c.Provider(ctx, guild, comms.WithAllowedChannels(chans...))

for msg := range p.Reader.Messages() {
    p.Actor.ReplyInThread(ctx, msg.Ref(), "help", answer)
}

Where to start

Look something up

What this does not do

The bot can post into a channel on its own initiative through Poster, but only into a channel its allowlist names. A post is plain text: no embeds and no attachments. The Discord provider refuses a post over Discord's 2000-character limit, counted after it adds the members Notify names, before sending it.

Attachments, direct messages, a channel's backlog, retries, logging and delivery guarantees are all deliberately absent, and each absence is load-bearing. A thread's history is readable; a channel's is not.

What this contract does not do is the page to read before planning anything around this module.

Design in four points

  • Reading and acting are separate. Ask for read-only and there is no Actor at all, so shadow mode is enforced by the type system rather than by remembering to check a flag.
  • Capabilities are opt-in. Moderation, member lookup, interactive components and slash commands are among ten optional interfaces found by type assertion. A read-only bridge with none of them is a legitimate provider.
  • Reconnect losses are surfaced. A reconnect that restarted the session rather than resuming dropped every message during the gap, with no error and nothing to notice. ConnState says so.
  • No vendor SDK in the core. This module has no third-party dependencies at all, and a guard test keeps it that way.

Further reading

Everything written about the estate, including the curated guides, is on the blog.

Ask phpbotscout

phpbotscout

He answers questions about the projects over on the Discord, citing the docs where they already cover it, and offering to raise an issue where they don't. Bring a bug, an idea, or a questionable engineering decision.

Join the Discord