messenger

README

Messenger

Messenger sends messages to a Discord webhook address while complying with the dynamic rate limiting (User needs to manage rate limit imposed on channel/server, the library cannot detect if other webhooks also post messages to the same channel/server).

Usage

Installing

go get github.com/qiyihuang/messenger

Sending messages

package main

import (
    "net/http"

    "github.com/qiyihuang/messenger"
)


func main() {
    hc := &http.Client{
        // Client config
    }
    url := "https://discord.com/api/webhooks/..."
    client, err := messenger.NewClient(hc, url)
    if err != nil {
        // handle when creating new client failed.
    }

    msgs := []messenger.Message{
        {
            Username: "Webhook username",
            Content:  "Message 1",
            Embeds: []messenger.Embed{
                // More fields please check go doc or Discord API.
                {Title: "Embed 1", Description: "Embed description 1"},
            },
        },
        {
            Username: "Webhook username",
            Content:  "Message 2",
        },
    }

    resp, err := client.Send(msgs)
    if err != nil {
        // handle when sending failed.
    }

    // ...
}

Discord message limits

Constants provided for managing message limits.

Documentation

Index

• Constants
• type Author
• type Client
  • func NewClient(hc HttpClient, url string) (*Client, error)
  • func (c *Client) Send(messages []Message) ([]*http.Response, error)
• type Embed
• type Field
• type File
• type Footer
• type HttpClient
• type Image
• type Message
• type Thumbnail
• type Timestamp
• type Video

Constants

const (
	// This library automatically divide message into smaller messages if it
	// exceeds the number of embed and embed total character limits.
	MessageEmbedNumLimit = 10
	MessageContentLimit  = 2000
	// Although not mentioned in documentation, in testings this limit seems
	// also enforced as the total character limit of multiple embeds in one
	// webhook message (excludes characters in "Content").
	EmbedTotalLimit       = 6000
	EmbedTitleLimit       = 256
	EmbedDescriptionLimit = 4096
	EmbedFieldNumLimit    = 25
	AuthorNameLimit       = 256
	FieldNameLimit        = 256
	FieldValueLimit       = 1024
	FooterTextLimit       = 2048
)

Limits Discord API enforces on webhook message.

Types

type Author

type Author struct {
	Name         string `json:"name,omitempty"`
	URL          string `json:"url,omitempty"` // URL on the Author name field.
	IconURL      string `json:"icon_url,omitempty"`
	ProxyIconURL string `json:"proxy_icon_url,omitempty"`
}

Author represents author object in an embed object.

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(hc HttpClient, url string) (*Client, error)

NewClient create a Client with valid formatted webhook url.

func (*Client) Send

func (c *Client) Send(messages []Message) ([]*http.Response, error)

Send request to Discord webhook url via http post. Adjusted to the dynamic rate limit

type Embed

type Embed struct {
	Fields      []Field   `json:"fields,omitempty"`
	Author      Author    `json:"author,omitempty"`
	Footer      Footer    `json:"footer,omitempty"`
	Video       Video     `json:"video,omitempty"`
	Thumbnail   Thumbnail `json:"thumbnail,omitempty"`
	Image       Image     `json:"image,omitempty"`
	Title       string    `json:"title,omitempty"`
	Description string    `json:"description,omitempty"`
	URL         string    `json:"url,omitempty"`
	Timestamp   Timestamp `json:"timestamp,omitempty"`
	Color       int       `json:"color,omitempty"`
}

Embed represents an embed object in message object.

type Field

type Field struct {
	Name   string `json:"name"`
	Value  string `json:"value"`
	Inline bool   `json:"inline,omitempty"`
}

Field represents field object in an embed object.

type File

type File struct {
	// Name must include file extension (e.g. .jpg)
	Name string
	// Usually not required for common file types, check Discord docs if not working.
	// https://discord.com/developers/docs/reference#image-data/
	ContentType string
	Reader      io.Reader
}

type Footer

type Footer struct {
	Text         string `json:"text"`
	IconURL      string `json:"icon_url,omitempty"`
	ProxyIconURL string `json:"proxy_icon_url,omitempty"`
}

Footer represents footer object in an embed object.

type HttpClient

type HttpClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HttpClient represent standard library http compatible clients.

type Image

type Image struct {
	URL      string `json:"url,omitempty"`
	ProxyURL string `json:"proxy_url,omitempty"`
	Height   int    `json:"height,omitempty"`
	Width    int    `json:"width,omitempty"`
}

Image represents the image object in an embed object.

type Message

type Message struct {
	Embeds   []Embed `json:"embeds,omitempty"`
	Files    []*File `json:"-"`
	Content  string  `json:"content,omitempty"`
	Username string  `json:"username,omitempty"`
}

Message represents a webhook message.

type Thumbnail

type Thumbnail struct {
	URL      string `json:"url,omitempty"`
	ProxyURL string `json:"proxy_url,omitempty"`
	Height   int    `json:"height,omitempty"`
	Width    int    `json:"width,omitempty"`
}

Thumbnail represents the thumbnail object in an embed object.

type Timestamp

type Timestamp string

Timestamp represents the timestamp string in an embed object Format timestamp using .UTC().Format("2006-01-02T15:04:05-0700"), Discord will convert it to local time on display.

type Video

type Video struct {
	URL      string `json:"url,omitempty"`
	ProxyURL string `json:"proxy_url,omitempty"`
	Height   int    `json:"height,omitempty"`
	Width    int    `json:"width,omitempty"`
}

Video represents the video object in an embed object.