transmitter

Documentation

Overview

Package transmitter provides functionality for transmitting arbitrary webhook messages to Discord.

The package provides the following functionality:

- Creating new webhooks, whenever necessary - Loading webhooks that we have previously created - Sending new messages - Editing messages, via message ID - Deleting messages, via message ID

The package has been designed for matterbridge, but with other Go bots in mind. The public API should be matterbridge-agnostic.

Index

• Variables
• type Transmitter
  • func New(session *discordgo.Session, guild string, title string, autoCreate bool) *Transmitter
  • func (t *Transmitter) AddWebhook(channelID string, webhook *discordgo.Webhook) bool
  • func (t *Transmitter) Edit(channelID string, messageID string, params *discordgo.WebhookParams) error
  • func (t *Transmitter) HasWebhook(id string) bool
  • func (t *Transmitter) RefreshGuildWebhooks(channelIDs []string) error
  • func (t *Transmitter) Send(channelID string, params *discordgo.WebhookParams) (*discordgo.Message, error)

Variables

var ErrPermissionDenied = errors.New("missing 'Manage Webhooks' permission")

ErrPermissionDenied is returned if the bot does not have permission to manage webhooks.

Bots can be granted a guild-wide permission and channel-specific permissions to manage webhooks. Despite potentially having guild-wide permission, channel specific overrides could deny a bot's permission to manage webhooks.

var ErrWebhookNotFound = errors.New("webhook for this channel and message does not exist")

ErrWebhookNotFound is returned when a valid webhook for this channel/message combination does not exist

Types

type Transmitter

type Transmitter struct {
	Log *log.Entry
	// contains filtered or unexported fields
}

A Transmitter represents a message manager for a single guild.

func New

func New(session *discordgo.Session, guild string, title string, autoCreate bool) *Transmitter

New returns a new Transmitter given a Discord session, guild ID, and title.

func (*Transmitter) AddWebhook

func (t *Transmitter) AddWebhook(channelID string, webhook *discordgo.Webhook) bool

AddWebhook allows you to register a channel's webhook with the transmitter.

func (*Transmitter) Edit

func (t *Transmitter) Edit(channelID string, messageID string, params *discordgo.WebhookParams) error

Edit will edit a message in a channel, if possible.

func (*Transmitter) HasWebhook

func (t *Transmitter) HasWebhook(id string) bool

HasWebhook checks whether the transmitter is using a particular webhook.

func (*Transmitter) RefreshGuildWebhooks

func (t *Transmitter) RefreshGuildWebhooks(channelIDs []string) error

RefreshGuildWebhooks loads "relevant" webhooks into the transmitter, with careful permission handling.

Notes:

- A webhook is "relevant" if it was created by this bot -- the ApplicationID should match the bot's ID. - The term "having permission" means having the "Manage Webhooks" permission. See ErrPermissionDenied for more information. - This function is additive and will not unload previously loaded webhooks. - A nil channelIDs slice is treated the same as an empty one.

If the bot has guild-wide permission:

1. it will load any "relevant" webhooks from the entire guild 2. the given slice is ignored

If the bot does not have guild-wide permission:

1. it will load any "relevant" webhooks in each channel 2. a single error will be returned if any error occurs (incl. if there is no permission for any of these channels)

If any channel has more than one "relevant" webhook, it will randomly pick one.

func (*Transmitter) Send

func (t *Transmitter) Send(channelID string, params *discordgo.WebhookParams) (*discordgo.Message, error)

Send transmits a message to the given channel with the provided webhook data, and waits until Discord responds with message data.