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 gostoat stoat.chat server.

NOTICE: This library is still a heavy work in progress. Expect unfinished and buggy features.

This Go package is not officially endorsed by or affiliated with stoat.chat

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 gofluxer package using this within your code.

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

Here is a basic example of a ping pong bot.

package 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.2 - June 4th, 2026

• Installing gostoat will now include github.com/gorilla/websocket v1.5.3 within the go.mod file which is required to use this package.
• Improved the logging text.

Version 0.0.1 - December 7th, 2025

• The first early release version of gostoat. This is a testing version so I can get suggestions on what to add or fix.
• 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

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

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))

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"`
}

type Message

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

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"`
}