matrix

go-matrix-bot

Go library for building Matrix bots with end-to-end encryption support, built on top of mautrix-go.

Pairs with go-ollama to build AI-powered chat assistants.

Features

• Simple, handler-based bot API — register functions, not interfaces
• End-to-end encryption out of the box (via mautrix crypto helper)
• Auto-join rooms on invite
• Send plain text, HTML, and markdown-formatted messages
• Mention users in replies
• Markdown-to-HTML conversion built in
• Graceful shutdown with context cancellation
• Works with go-ollama for AI responses

Installation

go get github.com/eslider/go-matrix-bot

For AI features (optional):

go get github.com/eslider/go-ollama

System dependency (required for encryption):

# Debian/Ubuntu
sudo apt-get install libolm-dev

Quick Start

1. Echo Bot

The simplest possible bot — replies with whatever you send it:

package main

import (
    "context"
    "fmt"
    "os"
    "os/signal"

    matrix "github.com/eslider/go-matrix-bot"
    "maunium.net/go/mautrix/event"
    "maunium.net/go/mautrix/id"
)

func main() {
    bot, _ := matrix.NewBot(matrix.GetEnvironmentConfig())

    bot.OnMessage(func(ctx context.Context, roomID id.RoomID, sender id.UserID, msg *event.MessageEventContent) {
        bot.SendText(ctx, roomID, "Echo: "+msg.Body)
    })

    ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
    defer cancel()

    go bot.Run(ctx)
    <-ctx.Done()
    bot.Stop()
}

2. AI Assistant (with Ollama)

A bot that forwards user messages to an Ollama LLM and returns formatted responses:

package main

import (
    "context"
    "os"
    "os/signal"
    "strings"

    matrix "github.com/eslider/go-matrix-bot"
    ollama "github.com/eslider/go-ollama"
    "maunium.net/go/mautrix/event"
    "maunium.net/go/mautrix/id"
)

func main() {
    bot, _ := matrix.NewBot(matrix.GetEnvironmentConfig())

    ai := ollama.NewOpenWebUiClient(&ollama.DSN{
        URL:   os.Getenv("OPEN_WEB_API_GENERATE_URL"),
        Token: os.Getenv("OPEN_WEB_API_TOKEN"),
    })

    bot.OnMessage(func(ctx context.Context, roomID id.RoomID, sender id.UserID, msg *event.MessageEventContent) {
        if !strings.HasPrefix(msg.Body, "::") {
            return
        }

        prompt := msg.Body[2:]
        var chunks []string

        ai.Query(ollama.Request{
            Model:  "llama3.2:3b",
            Prompt: prompt,
            Options: &ollama.RequestOptions{
                Temperature: ollama.Float(0.7),
            },
            OnJson: func(res ollama.Response) error {
                if res.Response != nil {
                    chunks = append(chunks, *res.Response)
                }
                return nil
            },
        })

        response := strings.Join(chunks, "")
        html := matrix.MarkdownToHTML(response)
        bot.SendReply(ctx, roomID, response, html, sender)
    })

    ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
    defer cancel()
    go bot.Run(ctx)
    <-ctx.Done()
    bot.Stop()
}

3. Command Bot (Multi-Command)

A bot with multiple commands like !help, !ping, !time, !ai:

bot.OnMessage(func(ctx context.Context, roomID id.RoomID, sender id.UserID, msg *event.MessageEventContent) {
    switch {
    case msg.Body == "!ping":
        bot.SendText(ctx, roomID, "pong!")

    case msg.Body == "!time":
        bot.SendText(ctx, roomID, time.Now().Format(time.RFC3339))

    case strings.HasPrefix(msg.Body, "!ai "):
        prompt := strings.TrimPrefix(msg.Body, "!ai ")
        // ... query Ollama and send response
    }
})

See the full commandbot example for a complete implementation with help text and code extraction.

Use Cases

Chat-Ops / DevOps Notifications

// Send deployment notifications to a Matrix room
bot.SendHTML(ctx, opsRoom,
    "Deploy complete: v1.2.3",
    matrix.MarkdownToHTML("**Deploy complete:** `v1.2.3` to production"),
)

AI Code Review Assistant

bot.OnMessage(func(ctx context.Context, roomID id.RoomID, sender id.UserID, msg *event.MessageEventContent) {
    if !strings.HasPrefix(msg.Body, "!review ") {
        return
    }

    code := strings.TrimPrefix(msg.Body, "!review ")
    var chunks []string

    ai.Query(ollama.Request{
        Model:  "llama3.2:3b",
        Prompt: "Review this code for bugs, security issues, and improvements:\n\n" + code,
        Options: &ollama.RequestOptions{Temperature: ollama.Float(0.3)},
        OnJson: func(res ollama.Response) error {
            if res.Response != nil {
                chunks = append(chunks, *res.Response)
            }
            return nil
        },
    })

    review := strings.Join(chunks, "")
    bot.SendReply(ctx, roomID, review, matrix.MarkdownToHTML(review), sender)
})

Monitoring Alert Bot

// Run a periodic health check and report to Matrix
go func() {
    ticker := time.NewTicker(5 * time.Minute)
    for range ticker.C {
        resp, err := http.Get("https://api.example.com/health")
        if err != nil || resp.StatusCode != 200 {
            bot.SendHTML(ctx, alertRoom,
                "ALERT: API is down!",
                matrix.MarkdownToHTML("**ALERT:** API health check failed"),
            )
        }
    }
}()

AI Translation Bot

bot.OnMessage(func(ctx context.Context, roomID id.RoomID, sender id.UserID, msg *event.MessageEventContent) {
    if !strings.HasPrefix(msg.Body, "!translate ") {
        return
    }

    text := strings.TrimPrefix(msg.Body, "!translate ")
    var chunks []string

    ai.Query(ollama.Request{
        Model:  "llama3.2:3b",
        Prompt: "Translate the following text to English. Only output the translation:\n\n" + text,
        Options: &ollama.RequestOptions{Temperature: ollama.Float(0.1)},
        OnJson: func(res ollama.Response) error {
            if res.Response != nil {
                chunks = append(chunks, *res.Response)
            }
            return nil
        },
    })

    translation := strings.Join(chunks, "")
    bot.SendReply(ctx, roomID, translation, matrix.MarkdownToHTML(translation), sender)
})

API Reference

Types

Config

type Config struct {
    Homeserver string // Matrix homeserver URL (e.g. "https://matrix.org")
    Username   string // Bot username (localpart, e.g. "mybot")
    Password   string // Bot password
    Database   string // SQLite database path for crypto state (default: "matrix-bot.db")
    Debug      bool   // Enable debug logging
}

MessageHandler

type MessageHandler func(ctx context.Context, roomID id.RoomID, sender id.UserID, message *event.MessageEventContent)

Functions

Bot Methods

Environment Variables

Examples

Related

• go-ollama — Ollama/Open WebUI API client with streaming
• go-onlyoffice — OnlyOffice Project Management API client
• go-gitea-helpers — Gitea API pagination helpers

License

MIT