harmony

package module
Version: v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 3, 2020 License: MIT Imports: 38 Imported by: 0

README

GoDoc License MIT Discord Build Status

Harmony

Harmony is a peaceful Go module for interacting with Discord's API.

Although this package is usable, it still is under active development so please don't use it for anything other than experiments, yet.

Contents

Installation

Make sure you have a working Go installation, if not see this page first.

Then, install this package with the go get command:

go get github.com/skwair/harmony

Note that go get will always pull the latest version from the master branch before Go 1.11. With newer versions and Go modules enabled, the latest minor or patch release will be downloaded. go get github.com/skwair/harmony@major.minor.patch can be used to download a specific version. See Go modules for more information.

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/skwair/harmony"
)

func main() {
    client, err := harmony.NewClient("your.bot.token")
    if err != nil {
        log.Fatal(err)
    }

    // Get information about the current user (the bot itself).
    u, err := client.CurrentUser().Get(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(u)
}

For information about how to create bots and more examples on how to use this package, check out the examples directory and the tests.

Testing

For now, only some end to end tests are provided with this module. To run them, you will need a valid bot token and a valid Discord server ID. The bot attached to the token must be in the server with administrator permissions.

  1. Create a Discord test server

From a Discord client and with you main account, simply create a new server. Then, right click on the new server and get it's ID.

Note that for the UI to have the Copy ID option when right clicking on the server, you will need to enable developer mode. You can find this option in User settings > Appearance > Advanced > Developer Mode.

  1. Create a bot and add it to the test Discord server

Create a bot (or use an existing one) and add it to the freshly created server.

See the example directory for information on how to create a bot and add it to a server.

  1. Set required environment variables and run the tests

Set HARMONY_TEST_BOT_TOKEN to the token of your bot and HARMONY_TEST_GUILD_ID to the ID of the server you created and simply run:

⚠️ For the tests to be reproducible, they will start by deleting ALL channels in the provided server. Please make sure to provide a server created ONLY for those tests. ⚠️

go test -v -race ./...

Step 1 and 2 must be done only once for initial setup. Once you have your bot token and the ID of your test server, you can run the tests as many times as you want.

How does it compare to DiscordGo?

Harmony exposes its API differently. It uses a resource-based approach which organizes methods by topic, greatly reducing the number of methods on the main Client type. The goal by doing this is to have a more friendly API which is easier to navigate.

Another key difference is in the "event handler" mechanism. Instead of having a single method that takes an interface{} as a parameter and guesses for which event you registered a handler based on its concrete type, this library provides a dedicated method for each event type, making it clear what signature your handler must have and ensuring it at compile time, not at runtime.

Each action that results in an entry in the audit log has a ...WithReason form, allowing to set a reason for the change (see the X-Audit-Log-Reason header documentation for more information).

Finally, this library has a full support of the context package, allowing the use of timeouts, deadlines and cancellation when interacting with Discord's API.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Original logo by Renee French, dressed with the cool t-shirt by @HlneChd.

Documentation

Overview

Package harmony provides an interface to the Discord API (https://discord.com/developers/docs/intro).

Getting started

The first thing you do is to create a Client. NewClient returns a new Client configured with sain defaults which should work just fine in most cases. However, should you need a more specific configuration, you can always tweak it with optional `ClientOption`s. See the documentation of NewClient and the ClientOption type for more information on how to do so.

client := harmony.NewClient("your.bot.token")

Once you have a Client, you can start interacting with the Discord API, but some methods (such as event handlers) won't be available until you connect to Discord's Gateway. You can do so by simply calling the Connect method of the Client:

if err = client.Connect(); err != nil {
	// Handle error
}
defer client.Disconnect() // Gracefully disconnect

It is only when successfully connected to the Gateway that your bot will appear as online and your Client will be able to receive events and send messages.

Using the HTTP API

Harmony's HTTP API is organized by resource. A resource maps to a core concept in the Discord world, such as a User or a Channel. Here is the list of resources you can interact with:

- Guild
- Channel
- CurrentUser
- Webhook
- Invite

Every interaction you can have with a resource can be accessed via methods attached to it. For example, if you wish to send a message to a channel:

msg, err := client.Channel("channel-id").SendMessage("content of the message")
if err != nil {
	// Handle error
}
// msg is the message sent

Registering event handlers

To receive messages, use the OnMessageCreate method and give it your handler. It will be called each time a message is sent to a channel your bot is in with the message as a parameter.

client.OnMessageCreate(func(msg *harmony.Message) {
	fmt.Println(msg.Content)
})

To register handlers for other types of events, see Client.On* methods.

Note that your handlers are called in their own goroutine, meaning whatever you do inside of them won't block future events.

Using the state

When connecting to Discord, a session state is created with initial data sent by Discord's Gateway. As events are received by the client, this state is constantly updated so it always have the newest data available.

This session state acts as a cache to avoid making requests over the HTTP API each time. If you need to get information about the current user:

user := client.State.CurrentUser()

Because this state might become memory hungry for bots that are in a very large number of servers, it can be disabled with the WithStateTracking option while creating the harmony client.

Index

Constants

Equivalent to all intents except privileged (GatewayIntentGuildMembers and GatewayIntentGuildPresences), OR'd.

Variables

View Source
var (
	// ErrGatewayNotConnected is returned when the client is not connected to the Gateway.
	ErrGatewayNotConnected = errors.New("gateway is not connected")
	// ErrAlreadyConnected is returned by Connect when a connection to the Gateway already exists.
	ErrAlreadyConnected = errors.New("already connected to the Gateway")
	// ErrInvalidSend is returned by Send when no files are provided.
	ErrInvalidSend = errors.New("no content, embed nor file provided")
	// ErrAlreadyConnectedToVoice is returned when trying to join a voice channel in
	// a guild where you are already have an active voice connection.
	ErrAlreadyConnectedToVoice = errors.New("already connected to a voice channel in this guild, consider using the SwitchVoiceChannel method")
	// ErrNotConnectedToVoice is returned when trying to switch to a different voice
	// channel in a guild where you are not yet connected to a voice channel.
	ErrNotConnectedToVoice = errors.New("not connected to a voice channel in this guild, use the JoinVoiceChannel method first")
)

Functions

func CreationTimeOf

func CreationTimeOf(id string) (time.Time, error)

CreationTimeOf returns the creation time of the given Discord ID (userID, guildID, channelID). For more information, see : https://discord.com/developers/docs/reference#snowflakes.

func DeleteWebhookWithToken

func DeleteWebhookWithToken(ctx context.Context, id, token string) error

DeleteWebhookWithToken is like DeleteWebhook except it does not require authentication.

Types

type APIError

type APIError struct {
	HTTPCode int      `json:"http_code"`
	Code     int      `json:"code"`
	Message  string   `json:"message"`
	Misc     []string `json:"_misc"`
}

APIError is a generic error returned by the Discord HTTP API.

func (APIError) Error

func (e APIError) Error() string

Error implements the error interface.

type Activity

type Activity struct {
	Name string       `json:"name"`
	Type ActivityType `json:"type"`
	// Stream url, is validated when type is Streaming.
	URL string `json:"url,omitempty"`
	// Unix timestamps for start and/or end of the game.
	Timestamps *ActivityTimestamp `json:"timestamps,omitempty"`
	// Application id for the game.
	ApplicationID string `json:"application_id,omitempty"`
	// What the player is currently doing.
	Details string `json:"details,omitempty"`
	// The user's current party status.
	State string `json:"state,omitempty"`
	// Information for the current party of the player.
	Party *ActivityParty `json:"party,omitempty"`
	// Images for the presence and their hover texts.
	Assets *ActivityAssets `json:"assets,omitempty"`
}

Activity represents a user activity (playing a game, streaming, etc.).

type ActivityAssets

type ActivityAssets struct {
	LargeImage string `json:"large_image,omitempty"`
	LargeText  string `json:"large_text,omitempty"`
	SmallImage string `json:"small_image,omitempty"`
	SmallText  string `json:"small_text,omitempty"`
}

ActivityAssets contains images for the presence and their hover texts.

type ActivityParty

type ActivityParty struct {
	ID   string `json:"id,omitempty"`
	Size []int  `json:"size,omitempty"` // Array of two integers (current_size, max_size).
}

ActivityParty contains information for the current party of the player.

type ActivityTimestamp

type ActivityTimestamp struct {
	Start int64 `json:"start,omitempty"`
	End   int64 `json:"end,omitempty"`
}

ActivityTimestamp is the unix time (in milliseconds) of when the activity starts and ends.

type ActivityType

type ActivityType int

ActivityType describes what the user is doing.

const (
	// ActivityPlaying will display "Playing {name}".
	ActivityPlaying ActivityType = iota
	// ActivityStreaming will display "Streaming {name}".
	ActivityStreaming
	// ActivityListening will display "Listening to {name}".
	ActivityListening
)

type ApplicationInfo added in v0.14.0

type ApplicationInfo struct {
	ID                  string   `json:"id,omitempty"`
	Name                string   `json:"name,omitempty"`
	Icon                string   `json:"icon,omitempty"`
	Description         string   `json:"description,omitempty"`
	RPCOrigins          []string `json:"rpc_origins,omitempty"`
	BotPublic           bool     `json:"bot_public,omitempty"`
	BotRequireCodeGrant bool     `json:"bot_require_code_grant,omitempty"`
	Owner               *User    `json:"owner,omitempty"`
	Summary             string   `json:"summary,omitempty"`
	VerifyKey           string   `json:"verify_key,omitempty"`
	Team                *Team    `json:"team,omitempty"`
	GuildID             string   `json:"guild_id,omitempty"`
	PrimarySKUID        string   `json:"primary_sku_id,omitempty"`
	Slug                string   `json:"slug,omitempty"`
	CoverImage          string   `json:"cover_image,omitempty"`
}

type AuditLogOption added in v0.11.0

type AuditLogOption func(*auditLogQuery)

AuditLogOption allows to customize a query to the audit log.

func WithBefore added in v0.11.0

func WithBefore(before string) AuditLogOption

WithBefore is used to paginate the audit log. The before parameter is the ID of the last audit log entry of our previous query.

func WithEntryType added in v0.11.0

func WithEntryType(typ audit.EntryType) AuditLogOption

WithEntryType sets the entry type the query must return.

func WithLimit added in v0.11.0

func WithLimit(limit int) AuditLogOption

WithLimit sets the limit the audit log query should return. It must be between 1 and 100 and defaults to 50 if not specified.

func WithUserID added in v0.11.0

func WithUserID(id string) AuditLogOption

WithUserID sets the user ID of the audit log query. It make the query only return audit log entries that have been creating for actions performed by this user.

type Ban

type Ban struct {
	Reason string
	User   *User
}

Ban represents a Guild ban.

type Channel

type Channel struct {
	ID                   string                 `json:"id,omitempty"`
	Type                 channel.Type           `json:"type,omitempty"`
	GuildID              string                 `json:"guild_id,omitempty"`
	Position             int                    `json:"position,omitempty"` // Sorting position of the channel.
	PermissionOverwrites []permission.Overwrite `json:"permission_overwrites,omitempty"`
	Name                 string                 `json:"name,omitempty"`
	Topic                string                 `json:"topic,omitempty"`
	NSFW                 bool                   `json:"nsfw,omitempty"`
	LastMessageID        string                 `json:"last_message_id,omitempty"`

	// For voice channels.
	Bitrate          int `json:"bitrate,omitempty"`
	UserLimit        int `json:"user_limit,omitempty"`
	RateLimitPerUser int `json:"rate_limit_per_user"`

	// For DMs.
	Recipients    []User `json:"recipients,omitempty"`
	Icon          string `json:"icon,omitempty"`
	OwnerID       string `json:"owner_id,omitempty"`
	ApplicationID string `json:"application_id,omitempty"` // Application id of the group DM creator if it is bot-created.

	ParentID         string    `json:"parent_id,omitempty"` // ID of the parent category for a channel.
	LastPinTimestamp time.Time `json:"last_pin_timestamp,omitempty"`
}

Channel represents a guild or DM channel within Discord.

func (*Channel) Clone

func (c *Channel) Clone() *Channel

Clone returns a clone of this Channel.

type ChannelPinsUpdate

type ChannelPinsUpdate struct {
	ChannelID        string    `json:"channel_id"`
	LastPinTimestamp time.Time `json:"last_pin_timestamp"`
}

ChannelPinsUpdate is Fired when a message is pinned or unpinned in a text channel.

type ChannelPosition

type ChannelPosition struct {
	ID       string `json:"id"`
	Position int    `json:"position"`
}

ChannelPosition is a pair of channel ID with its position.

type ChannelResource

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

ChannelResource is a resource that allows to perform various actions on a Discord channel. Create one with Client.Channel.

func (*ChannelResource) AddReaction

func (r *ChannelResource) AddReaction(ctx context.Context, messageID, emoji string) error

AddReaction adds a reaction to a message in the channel. This endpoint requires the 'READ_MESSAGE_HISTORY' permission to be present on the current user. Additionally, if nobody else has reacted to the message using this emoji, this endpoint requires the 'ADD_REACTIONS' permission to be present on the current user.

func (*ChannelResource) AddRecipient

func (r *ChannelResource) AddRecipient(ctx context.Context, channelID, recipientID string) error

AddRecipient adds a recipient to the existing Group DM or to a DM channel, creating a new Group DM channel. Groups have a limit of 10 recipients, including the current user.

func (*ChannelResource) CrossPostMessage added in v0.18.0

func (r *ChannelResource) CrossPostMessage(ctx context.Context, messageID string) (*Message, error)

Crosspost a message in a News Channel to following channels.

func (*ChannelResource) Delete

func (r *ChannelResource) Delete(ctx context.Context) (*Channel, error)

Delete is like DeleteWithReason but with no particular reason.

func (*ChannelResource) DeleteMessage

func (r *ChannelResource) DeleteMessage(ctx context.Context, messageID string) error

DeleteMessage is like DeleteMessageWithReason but with no particular reason.

func (*ChannelResource) DeleteMessageBulk

func (r *ChannelResource) DeleteMessageBulk(ctx context.Context, messageIDs []string) error

DeleteMessageBulk deletes multiple messages in a single request. This endpoint can only be used on guild channels and requires the 'MANAGE_MESSAGES' permission. Fires multiple Message Delete Gateway events. Any message IDs given that do not exist or are invalid will count towards the minimum and maximum message count (currently 2 and 100 respectively). Additionally, duplicated IDs will only be counted once. This endpoint will not delete messages older than 2 weeks, and will fail if any message provided is older than that.

func (*ChannelResource) DeleteMessageWithReason added in v0.11.0

func (r *ChannelResource) DeleteMessageWithReason(ctx context.Context, messageID, reason string) error

DeleteMessageWithReason deletes a message. If operating on a guild channel and trying to delete a message that was not sent by the current user, this endpoint requires the 'MANAGE_MESSAGES' permission. Fires a Message Delete Gateway event. The given reason will be set in the audit log entry for this action.

func (*ChannelResource) DeletePermission

func (r *ChannelResource) DeletePermission(ctx context.Context, channelID, targetID string) error

DeletePermission is like DeletePermissionWithReason but with no particular reason.

func (*ChannelResource) DeletePermissionWithReason added in v0.11.0

func (r *ChannelResource) DeletePermissionWithReason(ctx context.Context, channelID, targetID, reason string) error

DeletePermissionWithReason deletes the channel permission overwrite for a user or role in a channel. Only usable for guild channels. Requires the 'MANAGE_ROLES' permission. The given reason will be set in the audit log entry for this action.

func (*ChannelResource) DeleteWithReason added in v0.11.0

func (r *ChannelResource) DeleteWithReason(ctx context.Context, reason string) (*Channel, error)

DeleteWithReason deletes the channel, or closes the private message. Requires the 'MANAGE_CHANNELS' permission for the guild. Deleting a category does not delete its child channels; they will have their parent_id removed and a Channel Update Gateway event will fire for each of them. Returns the deleted channel on success. Fires a Channel Delete Gateway event. The given reason will be set in the audit log entry for this action.

func (*ChannelResource) EditEmbed

func (r *ChannelResource) EditEmbed(ctx context.Context, messageID, content string, embed *embed.Embed) (*Message, error)

EditEmbed is like EditMessage but with embedded content support.

func (*ChannelResource) EditMessage

func (r *ChannelResource) EditMessage(ctx context.Context, messageID, content string) (*Message, error)

EditMessage edits a previously sent message. You can only edit messages that have been sent by the current user. Fires a Message Update Gateway event. See EditEmbed if you need to edit some emended content.

func (*ChannelResource) Get

func (r *ChannelResource) Get(ctx context.Context) (*Channel, error)

Get returns the channel.

func (*ChannelResource) Invites

func (r *ChannelResource) Invites(ctx context.Context) ([]Invite, error)

Invites returns a list of invites (with invite metadata) for the channel. Only usable for guild channels. Requires the 'MANAGE_CHANNELS' permission.

func (*ChannelResource) Message

func (r *ChannelResource) Message(ctx context.Context, id string) (*Message, error)

Message returns a specific message in the channel. If operating on a guild channel, this endpoints requires the 'READ_MESSAGE_HISTORY' permission to be present on the current user.

func (*ChannelResource) Messages

func (r *ChannelResource) Messages(ctx context.Context, query string, limit int) ([]Message, error)

Messages returns messages in the channel. If operating on a guild channel, this endpoint requires the 'VIEW_CHANNEL' permission to be present on the current user. If the current user is missing the 'READ_MESSAGE_HISTORY' permission in the channel then this will return no messages (since they cannot read the message history). The query parameter is a message ID prefixed with one of the following character:

- '>' for fetching messages after
- '<' for fetching messages before
- '~' for fetching messages around

For example, to retrieve 50 messages around (25 before, 25 after) a message having the ID 221588207995121520, set query to "~221588207995121520". Limit is a positive integer between 1 and 100 that defaults to 50 if set to 0.

func (*ChannelResource) Modify

func (r *ChannelResource) Modify(ctx context.Context, settings *channel.Settings) (*Channel, error)

Modify is like ModifyWithReason but with no particular reason.

func (*ChannelResource) ModifyWithReason added in v0.11.0

func (r *ChannelResource) ModifyWithReason(ctx context.Context, settings *channel.Settings, reason string) (*Channel, error)

ModifyWithReason updates the channel's settings. Requires the 'MANAGE_CHANNELS' permission for the guild. Fires a Channel Update Gateway event. If modifying category, individual Channel Update events will fire for each child channel that also changes. The given reason will be set in the audit log entry for this action.

func (*ChannelResource) NewInvite

func (r *ChannelResource) NewInvite(ctx context.Context, settings *invite.Settings) (*Invite, error)

NewInvite is like NewInviteWithReason but with no particular reason.

func (*ChannelResource) NewInviteWithReason added in v0.11.0

func (r *ChannelResource) NewInviteWithReason(ctx context.Context, settings *invite.Settings, reason string) (*Invite, error)

NewInviteWithReason creates a new invite for the channel. Only usable for guild channels. Requires the CREATE_INSTANT_INVITE permission. The given reason will be set in the audit log entry for this action.

func (*ChannelResource) NewWebhook

func (r *ChannelResource) NewWebhook(ctx context.Context, name, avatar string) (*Webhook, error)

NewWebhook is like NewWebhookWithReason but with no particular reason.

func (*ChannelResource) NewWebhookWithReason added in v0.11.0

func (r *ChannelResource) NewWebhookWithReason(ctx context.Context, name, avatar, reason string) (*Webhook, error)

NewWebhookWithReason creates a new webhook for the channel. Requires the 'MANAGE_WEBHOOKS' permission. name must contain between 2 and 32 characters. avatar is an avatar data string, see https://discord.com/developers/docs/resources/user#avatar-data for more info. It can be left empty to have the default avatar. The given reason will be set in the audit log entry for this action.

func (*ChannelResource) PinMessage

func (r *ChannelResource) PinMessage(ctx context.Context, id string) error

PinMessage pins a message in the channel. Requires the 'MANAGE_MESSAGES' permission.

func (*ChannelResource) Pins

func (r *ChannelResource) Pins(ctx context.Context) ([]Message, error)

Pins returns all pinned messages in the channel as an array of messages.

func (*ChannelResource) Reactions added in v0.12.0

func (r *ChannelResource) Reactions(ctx context.Context, messageID, emoji string, limit int, before, after string) ([]User, error)

Reactions returns a list of users that reacted to a message with the given emoji. limit is the number of users to return and can be set to any value ranging from 1 to 100. If set to 0, it defaults to 25. If more than 100 users reacted with the given emoji, the before and after parameters can be used to fetch more users.

func (*ChannelResource) RemoveAllReactions

func (r *ChannelResource) RemoveAllReactions(ctx context.Context, messageID string) error

RemoveAllReactions removes all reactions on a message. This endpoint requires the 'MANAGE_MESSAGES' permission to be present on the current user.

func (*ChannelResource) RemoveAllReactionsForEmoji added in v0.17.0

func (r *ChannelResource) RemoveAllReactionsForEmoji(ctx context.Context, messageID, emoji string) error

RemoveAllReactionsForEmoji removes all reactions for the given emoji on a message. This endpoint requires the 'MANAGE_MESSAGES' permission to be present on the current user.

func (*ChannelResource) RemoveReaction

func (r *ChannelResource) RemoveReaction(ctx context.Context, messageID, emoji string) error

RemoveReaction removes a reaction the current user has made for the message.

func (*ChannelResource) RemoveRecipient

func (r *ChannelResource) RemoveRecipient(ctx context.Context, recipientID string) error

RemoveRecipient removes a recipient from the Group DM.

func (*ChannelResource) RemoveUserReaction

func (r *ChannelResource) RemoveUserReaction(ctx context.Context, messageID, userID, emoji string) error

RemoveUserReaction removes another user's reaction. This endpoint requires the 'MANAGE_MESSAGES' permission to be present on the current user.

func (*ChannelResource) Send added in v0.9.0

func (r *ChannelResource) Send(ctx context.Context, opts ...MessageOption) (*Message, error)

Send sends a message to the channel. If operating on a guild channel, this endpoint requires the 'SEND_MESSAGES' permission to be present on the current user. If the option WithTTS is set, the 'SEND_TTS_MESSAGES' permission is required for the message to be spoken. Returns the message sent. Fires a Message Create Gateway event. Before using this endpoint, you must connect to the gateway at least once.

func (*ChannelResource) SendMessage

func (r *ChannelResource) SendMessage(ctx context.Context, text string) (*Message, error)

SendMessage is a shorthand for Send(ctx, WithContent(text)).

func (*ChannelResource) TriggerTyping

func (r *ChannelResource) TriggerTyping(ctx context.Context) error

TriggerTyping triggers a typing indicator for the channel. Generally bots should not implement this route. However, if a bot is responding to a command and expects the computation to take a few seconds, this endpoint may be called to let the user know that the bot is processing their message. Fires a Typing Start Gateway event.

func (*ChannelResource) UnpinMessage

func (r *ChannelResource) UnpinMessage(ctx context.Context, id string) error

UnpinMessage deletes a pinned message in the channel. Requires the 'MANAGE_MESSAGES' permission.

func (*ChannelResource) UpdatePermissions

func (r *ChannelResource) UpdatePermissions(ctx context.Context, perms permission.Overwrite) error

UpdatePermissions is like UpdatePermissionsWithReason but with no particular reason.

func (*ChannelResource) UpdatePermissionsWithReason added in v0.11.0

func (r *ChannelResource) UpdatePermissionsWithReason(ctx context.Context, perms permission.Overwrite, reason string) error

UpdatePermissionsWithReason updates the channel permission overwrites for a user or role in the channel. If the channel permission overwrites do not not exist, they are created. Only usable for guild channels. Requires the 'MANAGE_ROLES' permission. The given reason will be set in the audit log entry for this action.

func (*ChannelResource) Webhooks

func (r *ChannelResource) Webhooks(ctx context.Context) ([]Webhook, error)

Webhooks returns webhooks for the channel.

type Client

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

Client is used to communicate with Discord's API. To start receiving events from the Gateway with a Client, you first need to call its Connect method.

func NewClient

func NewClient(token string, opts ...ClientOption) (*Client, error)

NewClient creates a new client to work with Discord's API. It is meant to be long lived and shared across your application. The token is automatically prefixed with "Bot ", which is a requirement by Discord for bot users. Automated normal user accounts (generally called "self-bots"), are not supported. To customize a Client, refer to available ClientOption.

func (*Client) ApplicationInfo added in v0.14.0

func (c *Client) ApplicationInfo(ctx context.Context) (*ApplicationInfo, error)

ApplicationInfo returns the bot's OAuth2 application info.

func (*Client) Channel

func (c *Client) Channel(id string) *ChannelResource

Channel returns a new channel resource to manage the channel with the given ID.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context) error

Connect connects and identifies the client to the Discord Gateway.

func (*Client) CreateGuild

func (c *Client) CreateGuild(ctx context.Context, name string) (*Guild, error)

CreateGuild creates a new guild with the given name. Returns the created guild on success. Fires a Guild Create Gateway event.

func (*Client) CurrentUser

func (c *Client) CurrentUser() *CurrentUserResource

CurrentUser returns a new resource to manage the current user.

func (*Client) Disconnect

func (c *Client) Disconnect()

Disconnect closes the connection to the Discord Gateway.

func (*Client) Gateway

func (c *Client) Gateway(ctx context.Context) (string, error)

Gateway returns a valid WSS URL, which the client can use for connecting.

func (*Client) GatewayBot

func (c *Client) GatewayBot(ctx context.Context) (string, int, error)

GatewayBot returns a valid WSS URL and the recommended number of shards to connect with.

func (*Client) Guild

func (c *Client) Guild(id string) *GuildResource

Guild returns a new guild resource to manage the guild with the given ID.

func (*Client) Invite

func (c *Client) Invite(code string) *InviteResource

Invite returns a new invite resource to manage the invite with the given code.

func (*Client) JoinVoiceChannel added in v0.14.0

func (c *Client) JoinVoiceChannel(ctx context.Context, guildID, channelID string, mute, deaf bool) (*voice.Connection, error)

JoinVoiceChannel will create a new voice connection to the given voice channel. If you already have an existing connection and want to switch to a different channel instead, use the SwitchVoiceChannel method. This method is safe to call from multiple goroutines, but connections will happen sequentially. To properly leave the voice channel, call LeaveVoiceChannel.

func (*Client) LeaveVoiceChannel added in v0.14.0

func (c *Client) LeaveVoiceChannel(ctx context.Context, guildID string) error

LeaveVoiceChannel notifies the Gateway we want the voice channel we are connected to in the given guild.

func (*Client) OnChannelCreate added in v0.6.0

func (c *Client) OnChannelCreate(f func(c *Channel))

OnChannelCreate registers the handler function for the "CHANNEL_CREATE" event. This event is fired when a new channel is created, relevant to the current user.

func (*Client) OnChannelDelete added in v0.6.0

func (c *Client) OnChannelDelete(f func(c *Channel))

OnChannelDelete registers the handler function for the "CHANNEL_DELETE" event. This event is fired when a channel is deleted, relevant to the current user.

func (*Client) OnChannelPinsUpdate added in v0.6.0

func (c *Client) OnChannelPinsUpdate(f func(cpu *ChannelPinsUpdate))

OnChannelPinsUpdate registers the handler function for the "CHANNEL_PINS_UPDATE" event. This event is fired when a message is pinned or unpinned, but not when a pinned message is deleted.

func (*Client) OnChannelUpdate added in v0.6.0

func (c *Client) OnChannelUpdate(f func(c *Channel))

OnChannelUpdate registers the handler function for the "CHANNEL_UPDATE" event. This event is fired when a channel is updated, relevant to the current user.

func (*Client) OnGuildBanAdd added in v0.6.0

func (c *Client) OnGuildBanAdd(f func(ban *GuildBan))

OnGuildBanAdd registers the handler function for the "GUILD_BAN_ADD" event.

func (*Client) OnGuildBanRemove added in v0.6.0

func (c *Client) OnGuildBanRemove(f func(ban *GuildBan))

OnGuildBanRemove registers the handler function for the "GUILD_BAN_REMOVE" event. This event is fired when a guild is updated.

func (*Client) OnGuildCreate added in v0.6.0

func (c *Client) OnGuildCreate(f func(g *Guild))

OnGuildCreate registers the handler function for the "GUILD_CREATE" event. This event can be sent in three different scenarios :

1. When a user is initially connecting, to lazily load and backfill information for all unavailable guilds sent in the Ready event.
2. When a Guild becomes available again to the client.
3. When the current user joins a new Guild.

func (*Client) OnGuildDelete added in v0.6.0

func (c *Client) OnGuildDelete(f func(g *UnavailableGuild))

OnGuildDelete registers the handler function for the "GUILD_DELETE" event. This event is fired when a guild becomes unavailable during a guild outage, or when the user leaves or is removed from a guild. If the unavailable field is not set, the user was removed from the guild.

func (*Client) OnGuildEmojisUpdate added in v0.6.0

func (c *Client) OnGuildEmojisUpdate(f func(emojis *GuildEmojis))

OnGuildEmojisUpdate registers the handler function for the "GUILD_EMOJIS_UPDATE" event. Fired when a guild's emojis have been updated.

func (*Client) OnGuildIntegrationsUpdate added in v0.6.0

func (c *Client) OnGuildIntegrationsUpdate(f func(u *GuildIntegrationUpdate))

OnGuildIntegrationsUpdate registers the handler function for the "GUILD_INTEGRATIONS_UPDATE" event. Fired when a guild integration is updated.

func (*Client) OnGuildInviteCreate added in v0.17.0

func (c *Client) OnGuildInviteCreate(f func(i *GuildInviteCreate))

OnGuildInviteCreate registers the handler function for the "GUILD_ROLE_DELETE" event. Fired when a guild role is deleted.

func (*Client) OnGuildInviteDelete added in v0.17.0

func (c *Client) OnGuildInviteDelete(f func(i *GuildInviteDelete))

OnGuildInviteDelete registers the handler function for the "GUILD_ROLE_DELETE" event. Fired when a guild role is deleted.

func (*Client) OnGuildMemberAdd added in v0.6.0

func (c *Client) OnGuildMemberAdd(f func(m *GuildMemberAdd))

OnGuildMemberAdd registers the handler function for the "GUILD_MEMBER_ADD" event. Fired when a new user joins a guild.

func (*Client) OnGuildMemberRemove added in v0.6.0

func (c *Client) OnGuildMemberRemove(f func(m *GuildMemberRemove))

OnGuildMemberRemove registers the handler function for the "GUILD_MEMBER_REMOVE" event. Fired when a user is removed from a guild (leave/kick/ban).

func (*Client) OnGuildMemberUpdate added in v0.6.0

func (c *Client) OnGuildMemberUpdate(f func(m *GuildMemberUpdate))

OnGuildMemberUpdate registers the handler function for the "GUILD_MEMBER_UPDATE" event. Fired when a guild member is updated.

func (*Client) OnGuildMembersChunk added in v0.6.0

func (c *Client) OnGuildMembersChunk(f func(m *GuildMembersChunk))

OnGuildMembersChunk registers the handler function for the "GUILD_MEMBERS_CHUNK" event. Sent in response to Guild Request Members.

func (*Client) OnGuildRoleCreate added in v0.6.0

func (c *Client) OnGuildRoleCreate(f func(r *GuildRole))

OnGuildRoleCreate registers the handler function for the "GUILD_ROLE_CREATE" event. Fired when a guild role is created.

func (*Client) OnGuildRoleDelete added in v0.6.0

func (c *Client) OnGuildRoleDelete(f func(r *GuildRoleDelete))

OnGuildRoleDelete registers the handler function for the "GUILD_ROLE_DELETE" event. Fired when a guild role is deleted.

func (*Client) OnGuildRoleUpdate added in v0.6.0

func (c *Client) OnGuildRoleUpdate(f func(r *GuildRole))

OnGuildRoleUpdate registers the handler function for the "GUILD_ROLE_UPDATE" event. Fired when a guild role is updated.

func (*Client) OnGuildUpdate added in v0.6.0

func (c *Client) OnGuildUpdate(f func(g *Guild))

OnGuildUpdate registers the handler function for the "GUILD_UPDATE" event.

func (*Client) OnMessageAck added in v0.6.0

func (c *Client) OnMessageAck(f func(ack *MessageAck))

OnMessageAck registers the handler function for the "MESSAGE_ACK" event.

func (*Client) OnMessageCreate added in v0.6.0

func (c *Client) OnMessageCreate(f func(m *Message))

OnMessageCreate registers the handler function for the "MESSAGE_CREATE" event. Fired when a message is created.

func (*Client) OnMessageDelete added in v0.6.0

func (c *Client) OnMessageDelete(f func(m *MessageDelete))

OnMessageDelete registers the handler function for the "MESSAGE_DELETE" event. Fired when a message is deleted.

func (*Client) OnMessageDeleteBulk added in v0.6.0

func (c *Client) OnMessageDeleteBulk(f func(mdb *MessageDeleteBulk))

OnMessageDeleteBulk registers the handler function for the "MESSAGE_DELETE_BULK" event. Fired when multiple messages are deleted at once.

func (*Client) OnMessageReactionAdd added in v0.6.0

func (c *Client) OnMessageReactionAdd(f func(r *MessageReaction))

OnMessageReactionAdd registers the handler function for the "MESSAGE_REACTION_ADD" event. Fired when a user adds a reaction to a message.

func (*Client) OnMessageReactionRemove added in v0.6.0

func (c *Client) OnMessageReactionRemove(f func(r *MessageReaction))

OnMessageReactionRemove registers the handler function for the "MESSAGE_REACTION_REMOVE" event. Fired when a user removes a reaction from a message.

func (*Client) OnMessageReactionRemoveAll added in v0.6.0

func (c *Client) OnMessageReactionRemoveAll(f func(r *MessageReactionRemoveAll))

OnMessageReactionRemoveAll registers the handler function for the "MESSAGE_REACTION_REMOVE_ALL" event. Fired when a user explicitly removes all reactions from a message.

func (*Client) OnMessageReactionRemoveEmoji added in v0.17.0

func (c *Client) OnMessageReactionRemoveEmoji(f func(r *MessageReactionRemoveEmoji))

HandleMessageReactionRemoveEmoji registers the handler function for the "MESSAGE_REACTION_REMOVE_ALL" event. Fired when a user explicitly removes all reactions from a message.

func (*Client) OnMessageUpdate added in v0.6.0

func (c *Client) OnMessageUpdate(f func(m *Message))

OnMessageUpdate registers the handler function for the "MESSAGE_UPDATE" event. Fired when a message is updated. Unlike creates, message updates may contain only a subset of the full message object payload (but will always contain an id and channel_id).

func (*Client) OnPresenceUpdate added in v0.6.0

func (c *Client) OnPresenceUpdate(f func(p *Presence))

OnPresenceUpdate registers the handler function for the "PRESENCE_UPDATE" event. This event is fired when a user's presence is updated for a guild. The user object within this event can be partial, the only field which must be sent is the id field, everything else is optional. Along with this limitation, no fields are required, and the types of the fields are not validated. Your client should expect any combination of fields and types within this event.

func (*Client) OnReady added in v0.6.0

func (c *Client) OnReady(f func(r *Ready))

OnReady registers the handler function for the "READY" event.

func (*Client) OnTypingStart added in v0.6.0

func (c *Client) OnTypingStart(f func(ts *TypingStart))

OnTypingStart registers the handler function for the "TYPING_START" event. Fired when a user starts typing in a channel.

func (*Client) OnUserUpdate added in v0.6.0

func (c *Client) OnUserUpdate(f func(u *User))

OnUserUpdate registers the handler function for the "USER_UPDATE" event. Fired when properties about the user change.

func (*Client) OnVoiceServerUpdate added in v0.6.0

func (c *Client) OnVoiceServerUpdate(f func(update *voice.ServerUpdate))

OnVoiceServerUpdate registers the handler function for the "VOICE_SERVER_UPDATE" event. Fired when a guild's voice server is updated. This is Fired when initially connecting to voice, and when the current voice instance fails over to a new server.

func (*Client) OnVoiceStateUpdate added in v0.6.0

func (c *Client) OnVoiceStateUpdate(f func(update *voice.StateUpdate))

OnVoiceStateUpdate registers the handler function for the "VOICE_STATE_UPDATE" event. Fired when someone joins/leaves/moves voice channels.

func (*Client) OnWebhooksUpdate added in v0.6.0

func (c *Client) OnWebhooksUpdate(f func(wu *WebhooksUpdate))

OnWebhooksUpdate registers the handler function for the "WEBHOOKS_UPDATE" event. Fired when a guild channel's webhook is created, updated, or deleted.

func (*Client) SwitchVoiceChannel added in v0.16.0

func (c *Client) SwitchVoiceChannel(ctx context.Context, guildID string, channelID string) error

SwitchVoiceChannel can be used to switch from a voice channel to another. It requires an active voice connection in the guild. You can get one with JoinVoiceChannel.

func (*Client) User added in v0.12.0

func (c *Client) User(ctx context.Context, id string) (*User, error)

User returns a user given its ID. Use "@me" as the ID to fetch information about the connected user. For every other IDs, this endpoint can only be used by bots.

func (*Client) VoiceRegions added in v0.12.0

func (c *Client) VoiceRegions(ctx context.Context, guildID string) ([]VoiceRegion, error)

VoiceRegions returns a list of available voice regions that can be used when creating or updating servers.

func (*Client) Webhook

func (c *Client) Webhook(id string) *WebhookResource

Webhook returns a new webhook resource to manage the webhook with the given ID.

type ClientOption

type ClientOption func(*Client)

ClientOption is a function that configures a Client. It is used in NewClient.

func WithBackoffStrategy

func WithBackoffStrategy(baseDelay, maxDelay time.Duration, factor, jitter float64) ClientOption

WithBackoffStrategy allows you to customize the backoff strategy used when trying to reconnect to the Discord Gateway after an error occurred (such as a network failure). Defaults to 1s (baseDelay), 120s (maxDelay), 1.6 (factor), 0.2 (jitter).

func WithBaseURL

func WithBaseURL(url string) ClientOption

WithBaseURL can be used to change de base URL of the API. This is used for testing. Deprecated.

func WithGatewayIntents added in v0.17.0

func WithGatewayIntents(i GatewayIntent) ClientOption

WithGatewayIntents allows to customize which Gateway Intents the client should subscribe to. See https://discord.com/developers/docs/topics/gateway#gateway-intents for more information. By default, the client subscribes to all unprivileged events.

func WithGuildSubscriptions added in v0.17.0

func WithGuildSubscriptions(y bool) ClientOption

WithGuildSubscriptions allows to set whether the client should identify to the Gateway with guild subscription enabled or not. Guild subscriptions are guild member presence updates and typing events. Defaults to true. While not deprecated, Guild Subscriptions have been superseded by Gateway Intents. It is recommended to use WithGatewayIntents for better results.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient can be used to specify the http.Client to use when making HTTP requests to the Discord HTTP API. Defaults to http.DefaultClient.

func WithLargeThreshold

func WithLargeThreshold(t int) ClientOption

WithLargeThreshold allows you to set the large threshold when connecting to the Gateway. This threshold will dictate the number of offline guild members are returned with a guild. See: https://discord.com/developers/docs/topics/gateway#request-guild-members for more details. Defaults to 250.

func WithLogger added in v0.12.0

func WithLogger(l log.Logger) ClientOption

WithLogger can be used to set the logger used by Harmony. Defaults to a standard logger reporting only errors. See the log package for more information about logging with Harmony.

func WithName added in v0.10.0

func WithName(n string) ClientOption

WithName sets the name of the client. It will be used to set the User-Agent of HTTP requests sent by the Client. Defaults to "Harmony".

func WithSharding

func WithSharding(current, total int) ClientOption

WithSharding allows you to specify a sharding configuration when connecting to the Gateway. See https://discord.com/developers/docs/topics/gateway#sharding for more details. Defaults to nothing, sharding is not enabled.

func WithStateTracking

func WithStateTracking(y bool) ClientOption

WithStateTracking allows you to specify whether the client is tracking the state of the current connection or not. Defaults to true.

type Connection

type Connection struct {
	ID           string        `json:"id"`
	Name         string        `json:"name"`
	Type         string        `json:"type"`
	Revoked      bool          `json:"revoked"`
	Integrations []Integration `json:"integrations"` // Partial server integrations.
}

Connection that the user has attached.

type CurrentUserResource

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

CurrentUserResource is a resource that allows to perform various actions on the current user. Create one with Client.CurrentUser.

func (*CurrentUserResource) Connections

func (r *CurrentUserResource) Connections(ctx context.Context) ([]Connection, error)

Connections returns a list of connections for the connected user.

func (*CurrentUserResource) DMs

func (r *CurrentUserResource) DMs(ctx context.Context) ([]Channel, error)

DMs returns the list of direct message channels the current user is in. This endpoint does not seem to be available for Bot users, always returning an empty list of channels.

func (*CurrentUserResource) Get

func (r *CurrentUserResource) Get(ctx context.Context) (*User, error)

Get returns the current user.

func (*CurrentUserResource) Guilds

Guilds returns a list of partial guilds the current user is a member of. This endpoint returns at most 100 guilds by default, which is the maximum number of guilds a non-bot user can join. Therefore, pagination is not needed for integrations that need to get a list of users' guilds.

func (*CurrentUserResource) LeaveGuild

func (r *CurrentUserResource) LeaveGuild(ctx context.Context, id string) error

LeaveGuild make the current user leave a guild given its ID.

func (*CurrentUserResource) Modify

func (r *CurrentUserResource) Modify(ctx context.Context, username, avatar string) (*User, error)

Modify modifies the current user account settings. Avatar is a Data URI scheme that supports JPG, GIF, and PNG formats. An example Data URI format is:

data:image/jpeg;base64,BASE64_ENCODED_JPEG_IMAGE_DATA

Ensure you use the proper header type (image/jpeg, image/png, image/gif) that matches the image data being provided.

func (*CurrentUserResource) NewDM

func (r *CurrentUserResource) NewDM(ctx context.Context, recipientID string) (*Channel, error)

NewDM creates a new DM channel with a user. Returns the created channel. If a DM channel already exist with this recipient, it does not create a new one and returns the existing one instead.

func (*CurrentUserResource) SetStatus

func (r *CurrentUserResource) SetStatus(status *Status) error

SetStatus sets the current user's status. You need to be connected to the Gateway to call this method, else it will return ErrGatewayNotConnected.

type Emoji

type Emoji struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	Roles         []Role `json:"roles"`
	User          *User  `json:"user"` // The user that created this emoji.
	RequireColons bool   `json:"require_colons"`
	Managed       bool   `json:"managed"`
	Animated      bool   `json:"animated"`
}

Emoji represents a Discord emoji (both standard and custom).

func (*Emoji) Clone

func (e *Emoji) Clone() *Emoji

Clone returns a clone of this Emoji.

type File

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

File represents a file that can be sent with Send and the WithFiles option.

func FileFromDisk added in v0.10.0

func FileFromDisk(filepath, name string) (*File, error)

FileFromDisk returns a File from a local, on disk file. If name is left empty, it will default to the name of the file on disk. Note that since Send is responsible for closing files opened by FileFromDisk, calling this function and *not* calling Send after can lead to resource leaks.

func FileFromReadCloser added in v0.10.0

func FileFromReadCloser(r io.ReadCloser, name string) *File

FileFromReadCloser returns a File given a ReadCloser and a name. If the name ends with a valid extension recognized by Discord's client applications, the file will be displayed inline in the channel instead of asking users to manually download it.

func FileFromURL added in v0.10.0

func FileFromURL(url, name string) (*File, error)

FileFromURL returns a File from a remote HTTP resource. If the name is left empty, it will default to the name of the file specified in the URL. Note that since Send is responsible for closing files opened by FileFromURL, calling this function and *not* calling Send after can lead to resource leaks.

type GatewayIntent added in v0.17.0

type GatewayIntent int

GatewayIntent specifies which events the Gateway should send to a client.

const (
	GatewayIntentGuild                  GatewayIntent = 1 << 0
	GatewayIntentGuildMembers           GatewayIntent = 1 << 1
	GatewayIntentGuildBans              GatewayIntent = 1 << 2
	GatewayIntentGuildEmojis            GatewayIntent = 1 << 3
	GatewayIntentGuildIntegrations      GatewayIntent = 1 << 4
	GatewayIntentGuildWebhooks          GatewayIntent = 1 << 5
	GatewayIntentGuildInvites           GatewayIntent = 1 << 6
	GatewayIntentGuildVoiceStates       GatewayIntent = 1 << 7
	GatewayIntentGuildPresences         GatewayIntent = 1 << 8
	GatewayIntentGuildMessages          GatewayIntent = 1 << 9
	GatewayIntentGuildMessageReactions  GatewayIntent = 1 << 10
	GatewayIntentGuildMessageTyping     GatewayIntent = 1 << 11
	GatewayIntentDirectMessages         GatewayIntent = 1 << 12
	GatewayIntentDirectMessageReactions GatewayIntent = 1 << 13
	GatewayIntentDirectMessageTyping    GatewayIntent = 1 << 14
)

List of gateway intents a client can subscribe to.

type Guild

type Guild struct {
	ID                          string                         `json:"id"`
	Name                        string                         `json:"name,omitempty"`
	Icon                        *string                        `json:"icon,omitempty"`
	Splash                      *string                        `json:"splash,omitempty"`
	Owner                       bool                           `json:"owner,omitempty"`
	OwnerID                     string                         `json:"owner_id,omitempty"`
	Permissions                 int                            `json:"permissions,omitempty"`
	Region                      string                         `json:"region,omitempty"`
	AFKChannelID                *string                        `json:"afk_channel_id,omitempty"`
	AFKTimeout                  int                            `json:"afk_timeout,omitempty"`
	EmbedEnabled                bool                           `json:"embed_enabled,omitempty"`
	EmbedChannelID              string                         `json:"embed_channel_id,omitempty"`
	VerificationLevel           guild.VerificationLevel        `json:"verification_level,omitempty"`
	DefaultMessageNotifications guild.DefaultNotificationLevel `json:"default_message_notifications,omitempty"`
	ExplicitContentFilter       guild.ExplicitContentFilter    `json:"explicit_content_filter,omitempty"`
	Roles                       []Role                         `json:"roles,omitempty"`
	Emojis                      []Emoji                        `json:"emojis,omitempty"`
	Features                    []string                       `json:"features,omitempty"`
	MFALevel                    int                            `json:"mfa_level,omitempty"`
	ApplicationID               *string                        `json:"application_id,omitempty"`
	WidgetEnabled               bool                           `json:"widget_enabled,omitempty"`
	WidgetChannelID             string                         `json:"widget_channel_id,omitempty"`
	SystemChannelID             *string                        `json:"system_channel_id,omitempty"`

	// Following fields are only sent within the GUILD_CREATE event.
	JoinedAt    time.Time     `json:"joined_at,omitempty"`
	Large       bool          `json:"large,omitempty"`
	Unavailable bool          `json:"unavailable,omitempty"`
	MemberCount int           `json:"member_count,omitempty"`
	VoiceStates []voice.State `json:"voice_states,omitempty"`
	Members     []GuildMember `json:"members,omitempty"`
	Channels    []Channel     `json:"channels,omitempty"`
	Presences   []Presence    `json:"presences,omitempty"`
}

Guild in Discord represents an isolated collection of users and channels, and are often referred to as "servers" in the UI.

func (*Guild) Clone

func (g *Guild) Clone() *Guild

Clone returns a clone of this Guild.

type GuildBan

type GuildBan struct {
	*User
	GuildID string `json:"guild_id"`
}

type GuildEmojis

type GuildEmojis struct {
	Emojis  []Emoji `json:"emojis"`
	GuildID string  `json:"guild_id"`
}

type GuildIntegrationUpdate added in v0.17.0

type GuildIntegrationUpdate struct {
	GuildID string `json:"guild_id"`
}

type GuildInviteCreate added in v0.17.0

type GuildInviteCreate struct {
	ChannelID      string    `json:"channel_id"`
	Code           string    `json:"code"`
	CreatedAt      time.Time `json:"created_at"`
	GuildID        string    `json:"guild_id"`
	Inviter        *User     `json:"inviter"`
	MaxAge         int       `json:"max_age"`
	MaxUses        int       `json:"max_uses"`
	TargetUser     *User     `json:"target_user"`
	TargetUserType int       `json:"target_user_type"`
	Temporary      bool      `json:"temporary"`
	Uses           int       `json:"uses"`
}

type GuildInviteDelete added in v0.17.0

type GuildInviteDelete struct {
	ChannelID string `json:"channel_id"`
	GuildID   string `json:"guild_id"`
	Code      string `json:"code"`
}

type GuildMember

type GuildMember struct {
	User     *User     `json:"user,omitempty"`
	Nick     string    `json:"nick,omitempty"`
	Roles    []string  `json:"roles,omitempty"` // Role IDs.
	JoinedAt time.Time `json:"joined_at,omitempty"`
	Deaf     bool      `json:"deaf,omitempty"`
	Mute     bool      `json:"mute,omitempty"`
}

GuildMember represents a User in a Guild.

func (*GuildMember) Clone

func (m *GuildMember) Clone() *GuildMember

Clone returns a clone of this GuildMember.

func (*GuildMember) HasRole

func (m *GuildMember) HasRole(id string) bool

HasRole returns whether this member has the given role. Note that this method does not try to fetch this member latest roles, it instead looks in the roles it already had when this member object was created.

func (*GuildMember) PermissionsIn

func (m *GuildMember) PermissionsIn(g *Guild, ch *Channel) (permissions int)

PermissionsIn returns the permissions of the Guild member in the given Guild and channel.

type GuildMemberAdd

type GuildMemberAdd struct {
	*GuildMember
	GuildID string `json:"guild_id"`
}

type GuildMemberRemove

type GuildMemberRemove struct {
	User    *User  `json:"user"`
	GuildID string `json:"guild_id"`
}

type GuildMemberUpdate

type GuildMemberUpdate struct {
	GuildID string   `json:"guild_id"`
	Roles   []string `json:"roles"`
	User    *User    `json:"user"`
	Nick    string   `json:"nick"`
}

type GuildMembersChunk

type GuildMembersChunk struct {
	GuildID string        `json:"guild_id"`
	Members []GuildMember `json:"members"`
}

type GuildResource

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

GuildResource is a resource that allows to perform various actions on a Discord guild. Create one with Client.Guild.

func (*GuildResource) AddIntegration

func (r *GuildResource) AddIntegration(ctx context.Context, id, typ string) error

AddIntegration attaches an integration from the current user to the guild. Requires the 'MANAGE_GUILD' permission. Fires a Guild Integrations Update Gateway event.

func (*GuildResource) AddMember

func (r *GuildResource) AddMember(ctx context.Context, userID, token string, settings *guild.MemberSettings) (*GuildMember, error)

AddMember adds a user to the guild, provided you have a valid oauth2 access token for the user with the guilds.join scope. Fires a Guild Member Add Gateway event. Requires the bot to have the CREATE_INSTANT_INVITE permission.

func (*GuildResource) AddMemberRole

func (r *GuildResource) AddMemberRole(ctx context.Context, userID, roleID string) error

AddMemberRole is like AddMemberRoleWithReason but with no particular reason.

func (*GuildResource) AddMemberRoleWithReason added in v0.11.0

func (r *GuildResource) AddMemberRoleWithReason(ctx context.Context, userID, roleID, reason string) error

AddMemberRole adds a role to a guild member. Requires the 'MANAGE_ROLES' permission. Fires a Guild Member Update Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) AuditLog added in v0.14.0

func (r *GuildResource) AuditLog(ctx context.Context, opts ...AuditLogOption) (*audit.Log, error)

AuditLog returns the audit log of the given Guild. Requires the 'VIEW_AUDIT_LOG' permission.

func (*GuildResource) Ban

func (r *GuildResource) Ban(ctx context.Context, userID string) error

Ban is a shorthand to ban a user with no reason and without deleting his messages. Requires the 'BAN_MEMBERS' permission. For more control, use the BanWithReason method.

func (*GuildResource) BanWithReason

func (r *GuildResource) BanWithReason(ctx context.Context, userID string, delMsgDays int, reason string) error

BanWithReason creates a guild ban, and optionally delete previous messages sent by the banned user. Requires the 'BAN_MEMBERS' permission. Parameter delMsgDays is the number of days to delete messages for (0-7). Fires a Guild Ban Add Gateway event.

func (*GuildResource) Bans

func (r *GuildResource) Bans(ctx context.Context) ([]Ban, error)

Bans returns a list of bans for the users banned from this guild. Requires the 'BAN_MEMBERS' permission.

func (*GuildResource) BeginPrune

func (r *GuildResource) BeginPrune(ctx context.Context, days int, computePruneCount bool) (pruneCount int, err error)

BeginPrune is like BeginPruneWithReason but with no particular reason.

func (*GuildResource) BeginPruneWithReason added in v0.11.0

func (r *GuildResource) BeginPruneWithReason(ctx context.Context, days int, computePruneCount bool, reason string) (pruneCount int, err error)

BeginPruneWithReason begins a prune operation. Requires the 'KICK_MEMBERS' permission. Returns the number of members that were removed in the prune operation if computePruneCount is set to true (not recommended for large guilds). Fires multiple Guild Member Remove Gateway events. The given reason will be set in the audit log entry for this action.

func (*GuildResource) ChangeNick

func (r *GuildResource) ChangeNick(ctx context.Context, name string) (string, error)

ChangeNick modifies the nickname of the current user (i.e.: the bot) for this guild. It returns the nickname on success. Requires the 'CHANGE_NICKNAME' permission. Fires a Guild Member Update Gateway event.

func (*GuildResource) Channels

func (r *GuildResource) Channels(ctx context.Context) ([]Channel, error)

Channels returns the list of channels in the guild.

func (*GuildResource) Delete

func (r *GuildResource) Delete(ctx context.Context) error

Delete deletes the guild permanently. Current user must be owner. Fires a Guild Delete Gateway event.

func (*GuildResource) DeleteEmoji

func (r *GuildResource) DeleteEmoji(ctx context.Context, emojiID string) error

DeleteEmoji is like DeleteEmojiWithReason but with no particular reason.

func (*GuildResource) DeleteEmojiWithReason added in v0.11.0

func (r *GuildResource) DeleteEmojiWithReason(ctx context.Context, emojiID, reason string) error

DeleteEmojiWithReason deletes the given emoji. Requires the 'MANAGE_EMOJIS' permission. Fires a Guild Emojis Update Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) DeleteRole

func (r *GuildResource) DeleteRole(ctx context.Context, id string) error

DeleteRole is like DeleteRoleWithReason but with no particular reason.

func (*GuildResource) DeleteRoleWithReason added in v0.11.0

func (r *GuildResource) DeleteRoleWithReason(ctx context.Context, id, reason string) error

DeleteRole deletes a guild role. Requires the 'MANAGE_ROLES' permission. Fires a Guild Role Delete Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) Embed

func (r *GuildResource) Embed(ctx context.Context) (*guild.Embed, error)

Embed returns the guild's embed. Requires the 'MANAGE_GUILD' permission.

func (*GuildResource) Emoji

func (r *GuildResource) Emoji(ctx context.Context, emojiID string) (*Emoji, error)

Emoji returns an emoji from the guild.

func (*GuildResource) Emojis

func (r *GuildResource) Emojis(ctx context.Context) ([]Emoji, error)

Emojis returns the list of emojis of the guild. Requires the MANAGE_EMOJIS permission.

func (*GuildResource) Get

func (r *GuildResource) Get(ctx context.Context) (*Guild, error)

Get returns the guild.

func (*GuildResource) Integrations

func (r *GuildResource) Integrations(ctx context.Context) ([]Integration, error)

Integrations returns the list of integrations for the guild. Requires the 'MANAGE_GUILD' permission.

func (*GuildResource) Invites

func (r *GuildResource) Invites(ctx context.Context) ([]Invite, error)

Invites returns the list of invites (with invite metadata) for the guild. Requires the 'MANAGE_GUILD' permission.

func (*GuildResource) Kick added in v0.12.0

func (r *GuildResource) Kick(ctx context.Context, userID string) error

Kick is like KickWithReason but with no particular reason.

func (*GuildResource) KickWithReason added in v0.12.0

func (r *GuildResource) KickWithReason(ctx context.Context, userID, reason string) error

Kick removes the given user from the guild. Requires 'KICK_MEMBERS' permission. Fires a Guild Member Remove Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) Member

func (r *GuildResource) Member(ctx context.Context, userID string) (*GuildMember, error)

Member returns a single guild member given its user ID.

func (*GuildResource) Members

func (r *GuildResource) Members(ctx context.Context, limit int, after string) ([]GuildMember, error)

Members returns a list of at most limit guild members, starting at after. limit must be between 1 and 1000 and will be set to those values if higher/lower. after is the ID of the guild member you want to get the list from, leave it empty to start from the beginning.

func (*GuildResource) Modify

func (r *GuildResource) Modify(ctx context.Context, settings *guild.Settings) (*Guild, error)

Modify is like ModifyWithReason but with no particular reason.

func (*GuildResource) ModifyChannelPosition

func (r *GuildResource) ModifyChannelPosition(ctx context.Context, pos []ChannelPosition) error

ModifyChannelPosition modifies the positions of a set of channel for the guild. Requires 'MANAGE_CHANNELS' permission. Fires multiple Channel Update Gateway events.

Only channels to be modified are required, with the minimum being a swap between at least two channels.

func (*GuildResource) ModifyEmbed

func (r *GuildResource) ModifyEmbed(ctx context.Context, embed *guild.Embed) (*guild.Embed, error)

ModifyEmbed modifies the guild embed of the guild. Requires the 'MANAGE_GUILD' permission.

func (*GuildResource) ModifyEmoji

func (r *GuildResource) ModifyEmoji(ctx context.Context, emojiID, name string, roles []string) (*Emoji, error)

ModifyEmoji is like ModifyEmojiWithReason but with no particular reason.

func (*GuildResource) ModifyEmojiWithReason added in v0.11.0

func (r *GuildResource) ModifyEmojiWithReason(ctx context.Context, emojiID, name string, roles []string, reason string) (*Emoji, error)

ModifyEmojiWithReason modifies the given emoji for the guild. Requires the 'MANAGE_EMOJIS' permission. Fires a Guild Emojis Update Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) ModifyIntegration

func (r *GuildResource) ModifyIntegration(ctx context.Context, id string, settings *integration.Settings) error

ModifyIntegration modifies the behavior and settings of a guild integration. Requires the 'MANAGE_GUILD' permission. Fires a Guild Integrations Update Gateway event.

func (*GuildResource) ModifyMember

func (r *GuildResource) ModifyMember(ctx context.Context, userID string, settings *guild.MemberSettings) error

ModifyMember is like ModifyMemberWithReason but with no particular reason.

func (*GuildResource) ModifyMemberWithReason added in v0.11.0

func (r *GuildResource) ModifyMemberWithReason(ctx context.Context, userID string, settings *guild.MemberSettings, reason string) error

ModifyMember modifies attributes of a guild member. Fires a Guild Member Update Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) ModifyRole

func (r *GuildResource) ModifyRole(ctx context.Context, id string, settings *role.Settings) (*Role, error)

ModifyRole is like ModifyRoleWithReason but with no particular reason.

func (*GuildResource) ModifyRolePositions

func (r *GuildResource) ModifyRolePositions(ctx context.Context, pos []RolePosition) ([]Role, error)

ModifyRolePositions modifies the positions of a set of roles for the guild. Requires 'MANAGE_ROLES' permission. Fires multiple Guild Role Update Gateway events.

func (*GuildResource) ModifyRoleWithReason added in v0.11.0

func (r *GuildResource) ModifyRoleWithReason(ctx context.Context, id string, settings *role.Settings, reason string) (*Role, error)

ModifyRole modifies a guild role. Requires the 'MANAGE_ROLES' permission. Fires a Guild Role Update Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) ModifyWithReason added in v0.11.0

func (r *GuildResource) ModifyWithReason(ctx context.Context, settings *guild.Settings, reason string) (*Guild, error)

ModifyWithReason modifies the guild's settings. Requires the 'MANAGE_GUILD' permission. Returns the updated guild on success. Fires a Guild Update Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) NewChannel

func (r *GuildResource) NewChannel(ctx context.Context, settings *channel.Settings) (*Channel, error)

NewChannel is like NewChannelWithReason but with no particular reason.

func (*GuildResource) NewChannelWithReason added in v0.11.0

func (r *GuildResource) NewChannelWithReason(ctx context.Context, settings *channel.Settings, reason string) (*Channel, error)

NewChannelWithReason creates a new channel in the guild. Requires the MANAGE_CHANNELS permission. Fires a Channel Create Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) NewEmoji

func (r *GuildResource) NewEmoji(ctx context.Context, name, image string, roles []string) (*Emoji, error)

NewEmoji is like NewEmojiWithReason but with no particular reason.

func (*GuildResource) NewEmojiWithReason added in v0.11.0

func (r *GuildResource) NewEmojiWithReason(ctx context.Context, name, image string, roles []string, reason string) (*Emoji, error)

NewEmojiWithReason creates a new emoji for the guild. image is the base64 encoded data of a 128*128 image. Requires the 'MANAGE_EMOJIS' permission. Fires a Guild Emojis Update Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) NewRole

func (r *GuildResource) NewRole(ctx context.Context, settings *role.Settings) (*Role, error)

NewRole is like NewRoleWithReason but with no particular reason.

func (*GuildResource) NewRoleWithReason added in v0.11.0

func (r *GuildResource) NewRoleWithReason(ctx context.Context, settings *role.Settings, reason string) (*Role, error)

NewRole creates a new role for the guild. Requires the 'MANAGE_ROLES' permission. Fires a Guild Role Create Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) PruneCount

func (r *GuildResource) PruneCount(ctx context.Context, days int) (int, error)

PruneCount returns the number of members that would be removed in a prune operation. Requires the 'KICK_MEMBERS' permission.

func (*GuildResource) RemoveIntegration

func (r *GuildResource) RemoveIntegration(ctx context.Context, id string) error

RemoveIntegration removes the attached integration for the guild. Requires the 'MANAGE_GUILD' permission. Fires a Guild Integrations Update Gateway event.

func (*GuildResource) RemoveMemberRole

func (r *GuildResource) RemoveMemberRole(ctx context.Context, userID, roleID string) error

RemoveMemberRole removes a role from a guild member. Requires the 'MANAGE_ROLES' permission. Fires a Guild Member Update Gateway event.

func (*GuildResource) RequestGuildMembers

func (r *GuildResource) RequestGuildMembers(query string, limit int) error

RequestGuildMembers is used to request offline members for the guild. When initially connecting, the gateway will only send offline members if a guild has less than the large_threshold members (value in the Gateway Identify). If a client wishes to receive additional members, they need to explicitly request them via this operation. The server will send Guild Members Chunk events in response with up to 1000 members per chunk until all members that match the request have been sent. query is a string that username starts with, or an empty string to return all members. limit is the maximum number of members to send or 0 to request all members matched. You need to be connected to the Gateway to call this method, else it will return ErrGatewayNotConnected.

func (*GuildResource) Roles

func (r *GuildResource) Roles(ctx context.Context) ([]Role, error)

Roles returns a list of roles for the guild. Requires the 'MANAGE_ROLES' permission.

func (*GuildResource) SyncIntegration

func (r *GuildResource) SyncIntegration(ctx context.Context, id string) error

SyncIntegration syncs a guild integration. Requires the 'MANAGE_GUILD' permission.

func (*GuildResource) Unban

func (r *GuildResource) Unban(ctx context.Context, userID string) error

Unban is like UnbanWithReason but with no particular reason.

func (*GuildResource) UnbanWithReason added in v0.11.0

func (r *GuildResource) UnbanWithReason(ctx context.Context, userID, reason string) error

Unban removes the ban for a user. Requires the 'BAN_MEMBERS' permissions. Fires a Guild Ban Remove Gateway event. The given reason will be set in the audit log entry for this action.

func (*GuildResource) VanityURL

func (r *GuildResource) VanityURL(ctx context.Context) (*Invite, error)

VanityURL returns a partial invite for the guild if that feature is enabled. Requires the 'MANAGE_GUILD' permission.

func (*GuildResource) VoiceRegions

func (r *GuildResource) VoiceRegions(ctx context.Context) ([]VoiceRegion, error)

VoiceRegions returns a list of available voice regions for the guild. Unlike the similar VoiceRegions method of the Client, this returns VIP servers when the guild is VIP-enabled.

func (*GuildResource) Webhooks

func (r *GuildResource) Webhooks(ctx context.Context) ([]Webhook, error)

Webhooks returns the list of webhooks in the guild. Requires the 'MANAGE_WEBHOOKS' permission.

type GuildRole

type GuildRole struct {
	GuildID string `json:"guild_id"`
	Role    *Role  `json:"role"`
}

type GuildRoleDelete

type GuildRoleDelete struct {
	GuildID string `json:"guild_id"`
	RoleID  string `json:"role_id"`
}

type Integration

type Integration struct {
	ID                string              `json:"id"`
	Name              string              `json:"name"`
	Type              string              `json:"type"`
	Enabled           bool                `json:"enabled"`
	Syncing           bool                `json:"syncing"`
	RoleID            string              `json:"role_id"`
	ExpireBehavior    int                 `json:"expire_behavior"`
	ExpireGracePeriod int                 `json:"expire_grace_period"`
	User              *User               `json:"user"`
	Account           *IntegrationAccount `json:"account"`
	SyncedAt          time.Time           `json:"synced_at"`
}

type IntegrationAccount

type IntegrationAccount struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

type Invite

type Invite struct {
	Code                     string   `json:"code,omitempty"`
	Guild                    *Guild   `json:"guild,omitempty"` // Nil if this invite is for a group DM channel.
	Channel                  *Channel `json:"channel,omitempty"`
	ApproximatePresenceCount int      `json:"approximate_presence_count,omitempty"`
	ApproximateMemberCount   int      `json:"approximate_member_count,omitempty"`

	InviteMetadata
}

Invite represents a code that when used, adds a user to a guild or group DM channel.

type InviteMetadata

type InviteMetadata struct {
	Inviter   *User     `json:"inviter,omitempty"`
	Uses      int       `json:"uses,omitempty"`
	MaxUses   int       `json:"max_uses,omitempty"`
	MaxAge    int       `json:"max_age,omitempty"`
	Temporary bool      `json:"temporary,omitempty"`
	CreatedAt time.Time `json:"created_at,omitempty"`
	Revoked   bool      `json:"revoked,omitempty"`
}

InviteMetadata contains additional information about an Invite.

type InviteResource

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

InviteResource is a resource that allows to perform various actions on a Discord invite. Create one with Client.Invite.

func (*InviteResource) Delete

func (r *InviteResource) Delete(ctx context.Context, reason string) (*Invite, error)

Delete is like DeleteWithReason but with no particular reason.

func (*InviteResource) DeleteWithReason added in v0.11.0

func (r *InviteResource) DeleteWithReason(ctx context.Context, reason string) (*Invite, error)

DeleteWithReason deletes the invite. Requires the MANAGE_CHANNELS permission. Returns the deleted invite on success. The given reason will be set in the audit log entry for this action.

func (*InviteResource) Get

func (r *InviteResource) Get(ctx context.Context, withCounts bool) (*Invite, error)

Get returns the invite. If withCounts is set to true, the returned invite will contain the approximate member counts.

type Message

type Message struct {
	ID        string `json:"id"`
	ChannelID string `json:"channel_id"`
	GuildID   string `json:"guild_id"`
	// Author of this message. Can be a user or a webhook.
	// Check the WebhookID field to know.
	Author *User `json:"author"`
	// Guild member info of the author that sent the message.
	// Only set for MESSAGE_CREATE and MESSAGE_UPDATE Gateway
	// events.
	Member          *GuildMember `json:"member"`
	Content         string       `json:"content"`
	Timestamp       time.Time    `json:"timestamp"`
	EditedTimestamp time.Time    `json:"edited_timestamp"`
	TTS             bool         `json:"tts"`
	// MentionEveryone is set to true if '@everyone' or '@here'
	// is set in the message's content.
	MentionEveryone bool `json:"mention_everyone"`
	// Mentions contains an array of users that where mentioned
	// in the message's content.
	Mentions []User `json:"mentions"`
	// MentionRoles contains an array of IDs of te roles that
	// were mentioned in the message's content.
	MentionRoles []string `json:"mention_roles"`
	// Not all channel mentions in a message will appear in mention_channels.
	// Only textual channels that are visible to everyone in a public guild
	// will ever be included. Only crossposted messages (via Channel Following)
	// currently include mention_channels at all. If no mentions in the message
	// meet these requirements, this field will not be sent.
	MentionChannels []channel.Mention    `json:"mention_channels"`
	Attachments     []message.Attachment `json:"attachments"` // Any attached files.
	Embeds          []embed.Embed        `json:"embeds"`      // Any embedded content.
	Reactions       []Reaction           `json:"reactions"`
	Nonce           string               `json:"nonce"` // Used for validating a message was sent.
	Pinned          bool                 `json:"pinned"`
	WebhookID       string               `json:"webhook_id"`
	Type            message.Type         `json:"type"`

	// Sent with Rich Presence-related chat embeds.
	Activity         *MessageActivity    `json:"activity"`
	Application      *MessageApplication `json:"application"`
	MessageReference *message.Reference  `json:"message_reference"`
	Flags            message.Flag        `json:"flags"`
}

Message represents a message sent in a channel within Discord. The author object follows the structure of the user object, but is only a valid user in the case where the message is generated by a user or bot user. If the message is generated by a webhook, the author object corresponds to the webhook's id, username, and avatar. You can tell if a message is generated by a webhook by checking for the webhook_id on the message object.

func ExecWebhook added in v0.12.0

func ExecWebhook(ctx context.Context, id, token string, p *WebhookParameters, wait bool) (*Message, error)

ExecWebhook executes the webhook with the id id given its token and some execution parameters. wait indicates if we should wait for server confirmation of message send before response. If wait is set to false, the returned Message will be nil even if there is no error.

type MessageAck

type MessageAck struct {
	ChannelID string `json:"channel_id"`
	MessageID string `json:"message_id"`
}

type MessageActivity

type MessageActivity struct {
	Type    MessageActivityType
	PartyID string
}

type MessageActivityType

type MessageActivityType int
const (
	Join MessageActivityType = iota
	Spectate
	Listen
	JoinRequest
)

type MessageApplication

type MessageApplication struct {
	ID          string
	CoverImage  string
	Description string
	Icon        string
	Name        string
}

type MessageDelete

type MessageDelete struct {
	ChannelID string `json:"channel_id"`
	MessageID string `json:"id"`
}

type MessageDeleteBulk

type MessageDeleteBulk struct {
	GuildID   string   `json:"guild_id"`
	ChannelID string   `json:"channel_id"`
	IDs       []string `json:"ids"`
}

type MessageOption added in v0.9.0

type MessageOption func(*createMessage)

MessageOption allows to customize the content of a message.

func WithContent added in v0.9.0

func WithContent(text string) MessageOption

WithContent sets the content of a message, up to 2000 characters

func WithEmbed added in v0.9.0

func WithEmbed(e *embed.Embed) MessageOption

WithEmbed sets the embed of a message. See embed sub package for more information about embeds.

func WithFiles added in v0.9.0

func WithFiles(files ...*File) MessageOption

WithFiles attach files to a message.

func WithNonce added in v0.9.0

func WithNonce(n string) MessageOption

WithNonce sets the nonce of a message. The nonce will be returned in the result and also transmitted to other clients.

func WithTTS added in v0.9.0

func WithTTS() MessageOption

WithTTS enables text to speech for a message.

type MessageReaction

type MessageReaction struct {
	UserID    string `json:"user_id"`
	GuildID   string `json:"guild_id"`
	ChannelID string `json:"channel_id"`
	MessageID string `json:"message_id"`
	Emoji     *Emoji `json:"emoji"`
}

type MessageReactionRemoveAll

type MessageReactionRemoveAll struct {
	GuildID   string `json:"guild_id"`
	ChannelID string `json:"channel_id"`
	MessageID string `json:"message_id"`
}

type MessageReactionRemoveEmoji added in v0.17.0

type MessageReactionRemoveEmoji struct {
	GuildID   string `json:"guild_id"`
	ChannelID string `json:"channel_id"`
	MessageID string `json:"message_id"`
	Emoji     *Emoji `json:"emoji"`
}

type PartialGuild

type PartialGuild struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Icon        string `json:"icon"`
	Owner       bool   `json:"owner"`
	Permissions int    `json:"permissions"`
}

PartialGuild is a subset of the Guild object, returned by the Discord API when fetching current user's guilds.

type Presence

type Presence struct {
	User    *User     `json:"user,omitempty"`
	Roles   []string  `json:"roles,omitempty"` // Array of IDs.
	Game    *Activity `json:"game,omitempty"`
	GuildID string    `json:"guild_id,omitempty"`
	Status  string    `json:"status,omitempty"` // Either "idle", "dnd", "online", or "offline".
}

Presence is a user's current state on a guild. This event is sent when a user's presence is updated for a guild.

func (*Presence) Clone

func (p *Presence) Clone() *Presence

Clone returns a clone of this Presence.

type Reaction

type Reaction struct {
	Count int    `json:"count"`
	Me    bool   `json:"me"`
	Emoji *Emoji `json:"emoji"`
}

Reaction is a reaction on a Discord message.

type Ready

type Ready struct {
	V               int            `json:"v"` // Gateway version.
	User            *User          `json:"user"`
	PrivateChannels []Channel      `json:"private_channels"`
	Guilds          []PartialGuild `json:"guilds"`
	SessionID       string         `json:"session_id"`
	Trace           []string       `json:"_trace"`
}

Ready is the Event fired by the Gateway after the client sent a valid Identify payload.

type Role

type Role struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Color       int    `json:"color"`    // Integer representation of hexadecimal color code.
	Hoist       bool   `json:"hoist"`    // Whether this role is pinned in the user listing.
	Position    int    `json:"position"` // Integer	position of this role.
	Permissions int    `json:"permissions"`
	Managed     bool   `json:"managed"` // Whether this role is managed by an integration.
	Mentionable bool   `json:"mentionable"`
}

Role represents a set of permissions attached to a group of users. Roles have unique names, colors, and can be "pinned" to the side bar, causing their members to be listed separately. Roles are unique per guild, and can have separate permission profiles for the global context (guild) and channel context.

func (*Role) Clone

func (r *Role) Clone() *Role

Clone returns a clone of this Role.

type RolePosition

type RolePosition struct {
	ID       string `json:"id"`
	Position int    `json:"position"`
}

RolePosition is a pair of role ID with its position. A higher position means it will appear before in the list.

type State

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

State is a cache of the state of the application that is updated in real-time as events are received from the Gateway. Objects returned by State methods are snapshots of original objects used internally by the State. This means they are safe to be used and modified but they won't be updated as new events are received.

func (*State) Channel

func (s *State) Channel(id string) *Channel

Channel returns a channel given its ID from the state.

func (*State) Channels

func (s *State) Channels() map[string]*Channel

Channels returns a map of channels ID to channels from the state.

func (*State) CurrentUser

func (s *State) CurrentUser() *User

CurrentUser returns the current user from the state.

func (*State) DM

func (s *State) DM(id string) *Channel

DM returns a DM given its ID from the state.

func (*State) DMs

func (s *State) DMs() map[string]*Channel

DMs returns a map of DM ID to DM from the state.

func (*State) GroupDM

func (s *State) GroupDM(id string) *Channel

GroupDM returns a group DM given its ID from the state.

func (*State) GroupDMs

func (s *State) GroupDMs() map[string]*Channel

GroupDMs returns a map of group DM ID to group DM from the state.

func (*State) Guild

func (s *State) Guild(id string) *Guild

Guild returns a guild given its ID from the state.

func (*State) Guilds

func (s *State) Guilds() map[string]*Guild

Guilds returns a map of guild ID to guild from the state.

func (*State) Presence

func (s *State) Presence(userID string) *Presence

Presence returns a presence given a user ID from the state.

func (*State) Presences

func (s *State) Presences() map[string]*Presence

Presences returns a map of user ID to presence from the state.

func (*State) RTT

func (s *State) RTT() time.Duration

RTT returns the Round Trip Time between the client and Discord's Gateway. It is calculated and updated when sending heartbeat payloads (roughly every minute).

func (*State) UnavailableGuild

func (s *State) UnavailableGuild(id string) *UnavailableGuild

UnavailableGuild returns an unavailable guild given its ID from the state.

func (*State) UnavailableGuilds

func (s *State) UnavailableGuilds() map[string]*UnavailableGuild

UnavailableGuilds returns a map of guild ID to unavailable guild from the state.

func (*State) User

func (s *State) User(id string) *User

User returns a user given its ID from the state.

func (*State) Users

func (s *State) Users() map[string]*User

Users returns a map of user ID to user from the state.

type Status

type Status struct {
	Since  int       `json:"since"`
	Game   *Activity `json:"game"`
	Status string    `json:"status"`
	AFK    bool      `json:"afk"`
}

Status is sent by the client to indicate a presence or status update.

type Team added in v0.14.0

type Team struct {
	Icon        string        `json:"icon,omitempty"`
	ID          string        `json:"id,omitempty"`
	Members     []*TeamMember `json:"members,omitempty"`
	OwnerUserID string        `json:"owner_member_id,omitempty"`
}

type TeamMember added in v0.14.0

type TeamMember struct {
	MembershipState int      `json:"membership_state,omitempty"`
	Permissions     []string `json:"permissions,omitempty"`
	TeadID          string   `json:"team_id,omitempty"`
	User            *User    `json:"user,omitempty"`
}

type TypingStart

type TypingStart struct {
	ChannelID string `json:"channel_id"`
	GuildID   string `json:"guild_id"`
	UserID    string `json:"user_id"`
	Timestamp int64  `json:"timestamp"`
}

type UnavailableGuild

type UnavailableGuild struct {
	ID          string `json:"id"`
	Unavailable *bool  `json:"unavailable"` // If not set, the connected user was removed from this Guild.
}

UnavailableGuild is a Guild that is not available, either because there is a guild outage or because the connected user was removed from this guild.

func (*UnavailableGuild) Clone

func (g *UnavailableGuild) Clone() *UnavailableGuild

Clone returns a clone of this UnavailableGuild.

type User

type User struct {
	ID            string `json:"id,omitempty"`
	Username      string `json:"username,omitempty"`
	Discriminator string `json:"discriminator,omitempty"`
	Avatar        string `json:"avatar,omitempty"`
	Bot           bool   `json:"bot,omitempty"`
	MFAEnabled    bool   `json:"mfa_enabled,omitempty"`
	Verified      bool   `json:"verified,omitempty"`
	Email         string `json:"email,omitempty"`
}

User in Discord is generally considered the base entity. Users can spawn across the entire platform, be members of guilds, participate in text and voice chat, and much more. Users are separated by a distinction of "bot" vs "normal." Although they are similar, bot users are automated users that are "owned" by another user. Unlike normal users, bot users do not have a limitation on the number of Guilds they can be a part of.

func (*User) AvatarURL

func (u *User) AvatarURL() string

AvatarURL returns the user's avatar URL.

func (*User) Clone

func (u *User) Clone() *User

Clone returns a clone of this User.

type ValidationError added in v0.7.0

type ValidationError struct {
	HTTPCode int
	Errors   map[string][]string
}

ValidationError is a validation error returned by the Discord HTTP API when it receives invalid parameters.

func (ValidationError) Error added in v0.7.0

func (e ValidationError) Error() string

Error implements the error interface.

type VoiceRegion

type VoiceRegion struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
	// Whether this is a vip-only server.
	VIP bool `json:"vip,omitempty"`
	// Whether this is a single server that is closest to the current user's client.
	Optimal bool `json:"optimal,omitempty"`
	// Whether this is a deprecated voice region (avoid switching to these.
	Deprecated bool `json:"deprecated,omitempty"`
	// Whether this is a custom voice region (used for events/etc).
	Custom bool `json:"custom,omitempty"`
}

VoiceRegion represents a voice region a guild can use or is using for its voice channels.

type Webhook

type Webhook struct {
	ID        string `json:"id,omitempty"`
	GuildID   string `json:"guild_id,omitempty"`
	ChannelID string `json:"channel_id,omitempty"`
	User      *User  `json:"user,omitempty"`
	Name      string `json:"name,omitempty"`
	Avatar    string `json:"avatar,omitempty"`
	Token     string `json:"token,omitempty"`
}

Webhook is a low-effort way to post messages to channels in Discord. It do not require a bot user or authentication to use.

func ModifyWebhookWithToken

func ModifyWebhookWithToken(ctx context.Context, id, token string, s *webhook.Settings) (*Webhook, error)

ModifyWebhookWithToken is like ModifyWebhook except this call does not require authentication, does not allow to change the channel_id parameter in the webhook settings, and does not return a user in the webhook.

func WebhookWithToken added in v0.12.0

func WebhookWithToken(ctx context.Context, id, token string) (*Webhook, error)

WebhookWithToken returns a webhook given its ID an a token. The user field in the returned webhook will be nil.

type WebhookParameters

type WebhookParameters struct {
	Content   string        `json:"content,omitempty"`
	Username  string        `json:"username,omitempty"`
	AvatarURL string        `json:"avatar_url,omitempty"`
	TTS       bool          `json:"tts,omitempty"`
	Embeds    []embed.Embed `json:"embeds,omitempty"`
	Files     []File        `json:"-"`
}

WebhookParameters are the parameters available when executing a webhook with ExecWebhook.

type WebhookResource

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

WebhookResource is a resource that allows to perform various actions on a Discord webhook. Create one with Client.Webhook.

func (*WebhookResource) Delete

func (r *WebhookResource) Delete(ctx context.Context) error

Delete is like DeleteWithReason but with no particular reason.

func (*WebhookResource) DeleteWithReason added in v0.11.0

func (r *WebhookResource) DeleteWithReason(ctx context.Context, reason string) error

DeleteWithReason deletes the webhook. The given reason will be set in the audit log entry for this action.

func (*WebhookResource) Get

func (r *WebhookResource) Get(ctx context.Context) (*Webhook, error)

Get returns the webhook.

func (*WebhookResource) Modify

func (r *WebhookResource) Modify(ctx context.Context, settings *webhook.Settings) (*Webhook, error)

Modify is like ModifyWithReason but with no particular reason.

func (*WebhookResource) ModifyWithReason added in v0.11.0

func (r *WebhookResource) ModifyWithReason(ctx context.Context, settings *webhook.Settings, reason string) (*Webhook, error)

ModifyWithReason modifies the webhook. Requires the 'MANAGE_WEBHOOKS' permission. The given reason will be set in the audit log entry for this action.

type WebhooksUpdate

type WebhooksUpdate struct {
	GuildID   string `json:"guild_id"`
	ChannelID string `json:"channel_id"`
}

Directories

Path Synopsis
Package embed contains builders to create Discord rich messages.
Package embed contains builders to create Discord rich messages.
examples
Package log defines an interface that can be implemented in order to provide a logger for Harmony.
Package log defines an interface that can be implemented in order to provide a logger for Harmony.
Package optional defines optional versions of primitive types that can be nil.
Package optional defines optional versions of primitive types that can be nil.
voiceutil
Package voiceutil provides utilities to work with harmony voice connections.
Package voiceutil provides utilities to work with harmony voice connections.
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL