stoat

README

gostoat

gostoat is an API wrapper that allows you to create stoat.chat bots as well as use stoat webhooks

If you need help with using the gostoat package, join the gstoat stoat.chat server.

NOTICE: This library is still a heavy work in progress.

Getting Started

This assumes you already have a Go environment on your system. If not, download Go from here. Make sure you have Go 1.21 or newer.

Install gostoat by using the following command.

go get github.com/MatthewsDevelopment/gostoat

After installing the package, import the gostoat package using this.

import "github.com/MatthewsDevelopment/gostoat"

Here is a basic example of a ping pong bot.

package mainpackage main

import (
	"log"
	"strings"
	"fmt"
	"github.com/MatthewsDevelopment/gostoat"
)

func main() {
	token := "STOATBOTTOKEN" // Replace STOATBOTTOKEN with your actual stoat.chat bot token.
	if token == "" {
		log.Fatal("STOATBOTTOKEN environment variable not set.")
	}

	client := stoat.NewClient(token)
	client.OnMessage(handlePingResponse)
	log.Fatal(client.ConnectAndRun())
}

func handlePingResponse(c *stoat.Client, m stoat.Message) {
	if strings.ToLower(strings.TrimSpace(m.Content)) == "ping" {
		content := "pong!"
		err := c.SendMessage(m.ChannelID, stoat.SendMessagePayload{
			Content: &content,
		})
		if err != nil {
			log.Printf("An error has occured: Failed to send 'pong' message: %v", err)
		}
	}
}

You can refer to the examples directory for more examples to see how to use this Go package

gostoat Update Notes:

Version 0.0.1 - December 7th, 2025

• Supports message and command handlers.
• Supports NSFW channel and bot owner checks.
• Supports using webhooks
• Uses MIT license.
• Added a example_pingpong.go example, a example_commands.go example, and a example_webhooks.go example.

Documentation

Index

• Constants
• func ExecuteWebhook(apiBaseURL, webhookID, webhookToken string, payload WebhookPayload) error
• func Ptr[T any](v T) *T
• type BotData
• type Channel
• type Client
  • func NewClient(token string) *Client
  • func (c *Client) ConnectAndRun() error
  • func (c *Client) FetchBotUser() (string, error)
  • func (c *Client) GetBotOwnerID() (string, error)
  • func (c *Client) GetChannel(channelID string) (*Channel, error)
  • func (c *Client) GetMessage(channelID, messageID string) (*Message, error)
  • func (c *Client) IsChannelNSFW(channelID string) (bool, error)
  • func (c *Client) OnCommand(name string, handler func(c *Client, cmd Command))
  • func (c *Client) OnMessage(handler func(c *Client, m Message))
  • func (c *Client) SendMessage(channelID string, payload SendMessagePayload) error
  • func (c *Client) SetAuthType(tokenType string) error
  • func (c *Client) SetBaseURLs(api, cdn, ws string)
  • func (c *Client) SetCommandPrefix(prefix string)
• type Command
• type Embed
• type Masquerade
• type Message
• type SendMessagePayload
• type User
• type WebhookPayload

Constants

const (
	DefaultAPIBaseURL = "https://api.stoat.chat"
	DefaultCDNBaseURL = "https://cdn.stoatusercontent.com"
	DefaultWSBaseURL  = "wss://events.stoat.chat"
)

const (
	BotTokenType     = "Bot"
	SessionTokenType = "Session"
)

Functions

func ExecuteWebhook

func ExecuteWebhook(apiBaseURL, webhookID, webhookToken string, payload WebhookPayload) error

func Ptr

func Ptr[T any](v T) *T

--- Helper Functions ---

Types

type BotData

type BotData struct {
	Owner string `json:"owner"`
}

type Channel

type Channel struct {
	ID   string `json:"_id"`
	NSFW bool   `json:"nsfw,omitempty"`
}

type Client

type Client struct {
	APIBaseURL string
	CDNBaseURL string
	WSBaseURL  string

	Token     string
	TokenType string
	Prefix    string

	HTTPClient *http.Client
	Conn       *websocket.Conn

	UserID string

	OnMessageHandlers []func(c *Client, m Message)
	CommandHandlers   map[string]func(c *Client, cmd Command)
}

func NewClient

func NewClient(token string) *Client

func (*Client) ConnectAndRun

func (c *Client) ConnectAndRun() error

--- WebSocket and Event Loop ---

func (*Client) FetchBotUser

func (c *Client) FetchBotUser() (string, error)

func (*Client) GetBotOwnerID

func (c *Client) GetBotOwnerID() (string, error)

func (*Client) GetChannel

func (c *Client) GetChannel(channelID string) (*Channel, error)

func (*Client) GetMessage

func (c *Client) GetMessage(channelID, messageID string) (*Message, error)

func (*Client) IsChannelNSFW

func (c *Client) IsChannelNSFW(channelID string) (bool, error)

func (*Client) OnCommand

func (c *Client) OnCommand(name string, handler func(c *Client, cmd Command))

func (*Client) OnMessage

func (c *Client) OnMessage(handler func(c *Client, m Message))

--- Handler Registration ---

func (*Client) SendMessage

func (c *Client) SendMessage(channelID string, payload SendMessagePayload) error

func (*Client) SetAuthType

func (c *Client) SetAuthType(tokenType string) error

func (*Client) SetBaseURLs

func (c *Client) SetBaseURLs(api, cdn, ws string)

func (*Client) SetCommandPrefix

func (c *Client) SetCommandPrefix(prefix string)

type Command

type Command struct {
	Message
	Name string
	Args []string
}

type Embed

type Embed struct {
	IconURL     *string `json:"icon_url,omitempty"`
	URL         *string `json:"url,omitempty"`
	Title       *string `json:"title,omitempty"`
	Description *string `json:"description,omitempty"`
	Media       *string `json:"media,omitempty"`
	Colour      *string `json:"colour,omitempty"`
}

type Masquerade

type Masquerade struct {
	Name   *string `json:"name,omitempty"`
	Avatar *string `json:"avatar,omitempty"`
}

--- API Payloads and Structs ---

type Message

type Message struct {
	ID        string `json:"_id"`
	ChannelID string `json:"channel"`
	Content   string `json:"content"`
	AuthorID  string `json:"author"`
}

--- Event Structures ---

type SendMessagePayload

type SendMessagePayload struct {
	Content    *string     `json:"content,omitempty"`
	Embeds     []Embed     `json:"embeds,omitempty"`
	Masquerade *Masquerade `json:"masquerade,omitempty"`
}

type User

type User struct {
	ID  string   `json:"_id"`
	Bot *BotData `json:"bot,omitempty"`
}

type WebhookPayload

type WebhookPayload struct {
	Content   *string `json:"content,omitempty"`
	Embeds    []Embed `json:"embeds,omitempty"`
	Username  *string `json:"username,omitempty"`
	AvatarURL *string `json:"avatar_url,omitempty"`
}