discordgo

package module
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Jan 27, 2016 License: BSD-3-Clause Imports: 20 Imported by: 18

README

Discordgo ==== [![GoDoc](https://godoc.org/github.com/bwmarrin/discordgo?status.svg)](https://godoc.org/github.com/bwmarrin/discordgo) [![Go report](http://goreportcard.com/badge/bwmarrin/discordgo)](http://goreportcard.com/report/bwmarrin/discordgo) [![Build Status](https://travis-ci.org/bwmarrin/discordgo.svg?branch=master)](https://travis-ci.org/bwmarrin/discordgo)

Discordgo is a Go package that provides low level bindings to the Discord chat client API.

  • See dgVoice for experimental voice support.

Join #go_discordgo Discord chat channel for support.

Getting Started

Installing

Discordgo has been tested to compile on Debian 8 (Go 1.3.3), FreeBSD 10 (Go 1.5.1), and Windows 7 (Go 1.5.2).

This assumes you already have a working Go environment, if not please see this page first.

$ go get github.com/bwmarrin/discordgo

Usage

Import the package into your project.

import "github.com/bwmarrin/discordgo"

Construct a new Discord client which can be used to access the variety of Discord API functions and to set callback functions for Discord events.

discord, err := discordgo.New("username", "password")

See Documentation and Examples below for more detailed information.

Documentation

NOTICE : This library and the Discord API are unfinished. Because of that there may be major changes to library functions, constants, and structures.

The Discordgo code is fairly well documented at this point and is currently the only documentation available. Both GoDoc and GoWalker (below) present that information in a nice format.

Examples

Below is a list of examples and other projects using Discordgo. Please submit an issue if you would like your project added or removed from this list

  • Basic - New A basic example using the easy New() helper function
  • Basic - API A basic example using the low level API functions.
  • Bruxism A chat bot for YouTube and Discord
  • GoGerard A modern bot for Discord
  • Digo A pluggable bot for your Discord server

Contributing

Contributions are very welcomed, however please follow the below guidelines.

  • First open an issue describing the bug or enhancement so it can be discussed.
  • Fork the develop branch and make your changes.
  • Try to match current naming conventions as closely as possible.
  • This package is intended to be a low level direct mapping of the Discord API so please avoid adding enhancements outside of that scope without first discussing it.
  • Create a Pull Request with your changes against the develop branch.

List of Discord APIs

See this chart for a feature comparison and list of other Discord API libraries.

Documentation

Overview

package discordgo provides Discord binding for Go

Index

Constants

View Source 
const VERSION = "0.10.0"

Discordgo Version, follows Symantic Versioning. (http://semver.org/)

Variables

View Source 
var (
	STATUS      = "https://status.discordapp.com/api/v2/"
	SM          = STATUS + "scheduled-maintenances/"
	SM_ACTIVE   = SM + "active.json"
	SM_UPCOMING = SM + "upcoming.json"

	DISCORD  = "https://discordapp.com" // TODO consider removing
	API      = DISCORD + "/api/"
	GUILDS   = API + "guilds/"
	CHANNELS = API + "channels/"
	USERS    = API + "users/"
	GATEWAY  = API + "gateway"

	AUTH            = API + "auth/"
	LOGIN           = AUTH + "login"
	LOGOUT          = AUTH + "logout"
	VERIFY          = AUTH + "verify"
	VERIFY_RESEND   = AUTH + "verify/resend"
	FORGOT_PASSWORD = AUTH + "forgot"
	RESET_PASSWORD  = AUTH + "reset"
	REGISTER        = AUTH + "register"

	VOICE         = API + "/voice/"
	VOICE_REGIONS = VOICE + "regions"
	VOICE_ICE     = VOICE + "ice"

	TUTORIAL            = API + "tutorial/"
	TUTORIAL_INDICATORS = TUTORIAL + "indicators"

	TRACK        = API + "track"
	SSO          = API + "sso"
	REPORT       = API + "report"
	INTEGRATIONS = API + "integrations"

	USER             = func(uID string) string { return USERS + uID }
	USER_AVATAR      = func(uID, aID string) string { return USERS + uID + "/avatars/" + aID + ".jpg" }
	USER_SETTINGS    = func(uID string) string { return USERS + uID + "/settings" }
	USER_GUILDS      = func(uID string) string { return USERS + uID + "/guilds" }
	USER_CHANNELS    = func(uID string) string { return USERS + uID + "/channels" }
	USER_DEVICES     = func(uID string) string { return USERS + uID + "/devices" }
	USER_CONNECTIONS = func(uID string) string { return USERS + uID + "/connections" }

	GUILD              = func(gID string) string { return GUILDS + gID }
	GUILD_INIVTES      = func(gID string) string { return GUILDS + gID + "/invites" }
	GUILD_CHANNELS     = func(gID string) string { return GUILDS + gID + "/channels" }
	GUILD_MEMBER       = func(gID, uID string) string { return GUILDS + gID + "/members/" + uID }
	GUILD_BANS         = func(gID string) string { return GUILDS + gID + "/bans" }
	GUILD_BAN          = func(gID, uID string) string { return GUILDS + gID + "/bans/" + uID }
	GUILD_INTEGRATIONS = func(gID string) string { return GUILDS + gID + "/integrations" }
	GUILD_ROLES        = func(gID string) string { return GUILDS + gID + "/roles" }
	GUILD_ROLE         = func(gID, rID string) string { return GUILDS + gID + "/roles/" + rID }
	GUILD_INVITES      = func(gID string) string { return GUILDS + gID + "/invites" }
	GUILD_EMBED        = func(gID string) string { return GUILDS + gID + "/embed" }
	GUILD_PRUNE        = func(gID string) string { return GUILDS + gID + "/prune" }
	GUILD_ICON         = func(gID, hash string) string { return GUILDS + gID + "/icons/" + hash + ".jpg" }
	GUILD_SPLASH       = func(gID, hash string) string { return GUILDS + gID + "/splashes/" + hash + ".jpg" }

	CHANNEL             = func(cID string) string { return CHANNELS + cID }
	CHANNEL_PERMISSIONS = func(cID string) string { return CHANNELS + cID + "/permissions" }
	CHANNEL_PERMISSION  = func(cID, tID string) string { return CHANNELS + cID + "/permissions/" + tID }
	CHANNEL_INVITES     = func(cID string) string { return CHANNELS + cID + "/invites" }
	CHANNEL_TYPING      = func(cID string) string { return CHANNELS + cID + "/typing" }
	CHANNEL_MESSAGES    = func(cID string) string { return CHANNELS + cID + "/messages" }
	CHANNEL_MESSAGE     = func(cID, mID string) string { return CHANNELS + cID + "/messages/" + mID }
	CHANNEL_MESSAGE_ACK = func(cID, mID string) string { return CHANNELS + cID + "/messages/" + mID + "/ack" }

	INVITE = func(iID string) string { return API + "invite/" + iID }

	INTEGRATIONS_JOIN = func(iID string) string { return API + "integrations/" + iID + "/join" }

	EMOJI = func(eID string) string { return API + "emojis/" + eID + ".png" }
)
View Source 
var ErrJSONUnmarshal = errors.New("json unmarshal")

Functions

This section is empty.

Types

type Attachment 

type Attachment struct {
	ID       string `json:"id"`
	URL      string `json:"url"`
	ProxyURL string `json:"proxy_url"`
	Width    int    `json:"width"`
	Height   int    `json:"height"`
	Filename string `json:"filename"`
	Size     int    `json:"size"`
}

An Attachment stores data for message attachments.

type Channel 

type Channel struct {
	ID                   string                 `json:"id"`
	GuildID              string                 `json:"guild_id"`
	Name                 string                 `json:"name"`
	Topic                string                 `json:"topic"`
	Position             int                    `json:"position"`
	Type                 string                 `json:"type"`
	PermissionOverwrites []*PermissionOverwrite `json:"permission_overwrites"`
	IsPrivate            bool                   `json:"is_private"`
	LastMessageID        string                 `json:"last_message_id"`
	Recipient            *User                  `json:"recipient"`
	Messages             []*Message             `json:"-"`
}

A Channel holds all data related to an individual Discord channel.

type Embed 

type Embed struct {
	URL         string `json:"url"`
	Type        string `json:"type"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Thumbnail   *struct {
		URL      string `json:"url"`
		ProxyURL string `json:"proxy_url"`
		Width    int    `json:"width"`
		Height   int    `json:"height"`
	} `json:"thumbnail"`
	Provider *struct {
		URL  string `json:"url"`
		Name string `json:"name"`
	} `json:"provider"`
	Author *struct {
		URL  string `json:"url"`
		Name string `json:"name"`
	} `json:"author"`
	Video *struct {
		URL    string `json:"url"`
		Width  int    `json:"width"`
		Height int    `json:"height"`
	} `json:"video"`
}

An Embed stores data for message embeds.

type Emoji added in v0.8.0 

type Emoji struct {
	Roles         []string `json:"roles"`
	RequireColons bool     `json:"require_colons"`
	Name          string   `json:"name"`
	Managed       bool     `json:"managed"`
	ID            string   `json:"id"`
}

type Event 

type Event struct {
	Type      string          `json:"t"`
	State     int             `json:"s"`
	Operation int             `json:"op"`
	Direction int             `json:"dir"`
	RawData   json.RawMessage `json:"d"`
}

An Event provides a basic initial struct for all websocket event.

type Game added in v0.7.0 

type Game struct {
	Name string `json:"name"`
}

type Guild 

type Guild struct {
	ID             string        `json:"id"`
	Name           string        `json:"name"`
	Icon           string        `json:"icon"`
	Region         string        `json:"region"`
	AfkTimeout     int           `json:"afk_timeout"`
	AfkChannelID   string        `json:"afk_channel_id"`
	EmbedChannelID string        `json:"embed_channel_id"`
	EmbedEnabled   bool          `json:"embed_enabled"`
	OwnerID        string        `json:"owner_id"`
	Large          bool          `json:"large"`     // ??
	JoinedAt       string        `json:"joined_at"` // make this a timestamp
	Splash         string        `json:"splash"`
	Roles          []*Role       `json:"roles"`
	Emojis         []*Emoji      `json:"emojis"`
	Members        []*Member     `json:"members"`
	Presences      []*Presence   `json:"presences"`
	Channels       []*Channel    `json:"channels"`
	VoiceStates    []*VoiceState `json:"voice_states"`
}

A Guild holds all data related to a specific Discord Guild. Guilds are also sometimes referred to as Servers in the Discord client.

type GuildBan added in v0.8.0 

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

A GuildBan stores data for a guild ban.

type GuildEmojisUpdate added in v0.8.0 

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

A GuildEmojisUpdate stores data for a guild emoji update event.

type GuildIntegrationsUpdate 

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

A GuildIntegrationsUpdate stores data for the guild integrations update websocket event.

type GuildRole 

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

A GuildRole stores data for guild role websocket events.

type GuildRoleDelete 

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

A GuildRoleDelete stores data for the guild role delete websocket event.

type ICEServer 

type ICEServer struct {
	URL        string `json:"url"`
	Username   string `json:"username"`
	Credential string `json:"credential"`
}

A ICEServer stores data for a specific voice ICE server.

type Invite 

type Invite struct {
	MaxAge    int      `json:"max_age"`
	Code      string   `json:"code"`
	Guild     *Guild   `json:"guild"`
	Revoked   bool     `json:"revoked"`
	CreatedAt string   `json:"created_at"` // TODO make timestamp
	Temporary bool     `json:"temporary"`
	Uses      int      `json:"uses"`
	MaxUses   int      `json:"max_uses"`
	Inviter   *User    `json:"inviter"`
	XkcdPass  bool     `json:"xkcdpass"`
	Channel   *Channel `json:"channel"`
}

A Invite stores all data related to a specific Discord Guild or Channel invite.

type Member 

type Member struct {
	GuildID  string   `json:"guild_id"`
	JoinedAt string   `json:"joined_at"`
	Deaf     bool     `json:"deaf"`
	Mute     bool     `json:"mute"`
	User     *User    `json:"user"`
	Roles    []string `json:"roles"`
}

A Member stores user information for Guild members.

type Message 

type Message struct {
	ID              string        `json:"id"`
	Author          *User         `json:"author"`
	Content         string        `json:"content"`
	Attachments     []*Attachment `json:"attachments"`
	Tts             bool          `json:"tts"`
	Embeds          []*Embed      `json:"embeds"`
	Timestamp       string        `json:"timestamp"`
	MentionEveryone bool          `json:"mention_everyone"`
	EditedTimestamp string        `json:"edited_timestamp"`
	Mentions        []*User       `json:"mentions"`
	ChannelID       string        `json:"channel_id"`
}

A Message stores all data related to a specific Discord message.

func (*Message) ContentWithMentionsReplaced added in v0.8.0 

func (m *Message) ContentWithMentionsReplaced() string

ContentWithMentionsReplaced will replace all @<id> mentions with the username of the mention.

type MessageAck 

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

A MessageAck stores data for the message ack websocket event.

type PermissionOverwrite 

type PermissionOverwrite struct {
	ID    string `json:"id"`
	Type  string `json:"type"`
	Deny  int    `json:"deny"`
	Allow int    `json:"allow"`
}

A PermissionOverwrite holds permission overwrite data for a Channel

type Presence 

type Presence struct {
	User   *User  `json:"user"`
	Status string `json:"status"`
	Game   *Game  `json:"game"`
}

A Presence stores the online, offline, or idle and game status of Guild members.

type PresenceUpdate 

type PresenceUpdate struct {
	User    *User    `json:"user"`
	Status  string   `json:"status"`
	Roles   []string `json:"roles"`
	GuildID string   `json:"guild_id"`
	Game    *Game    `json:"game"`
}

A PresenceUpdate stores data for the pressence update websocket event.

type RateLimit added in v0.9.0 

type RateLimit struct {
	Bucket     string        `json:"bucket"`
	Message    string        `json:"message"`
	RetryAfter time.Duration `json:"retry_after"`
}

type ReadState 

type ReadState struct {
	MentionCount  int
	LastMessageID string `json:"last_message_id"`
	ID            string `json:"id"`
}

A ReadState stores data on the read state of channels.

type Ready 

type Ready struct {
	Version           int           `json:"v"`
	SessionID         string        `json:"session_id"`
	HeartbeatInterval time.Duration `json:"heartbeat_interval"`
	User              *User         `json:"user"`
	ReadState         []*ReadState  `json:"read_state"`
	PrivateChannels   []*Channel    `json:"private_channels"`
	Guilds            []*Guild      `json:"guilds"`
}

A Ready stores all data for the websocket READY event.

type Role 

type Role struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Managed     bool   `json:"managed"`
	Color       int    `json:"color"`
	Hoist       bool   `json:"hoist"`
	Position    int    `json:"position"`
	Permissions int    `json:"permissions"`
}

A Role stores information about Discord guild member roles.

type Session 

type Session struct {
	sync.RWMutex

	// General configurable settings.
	Token string // Authentication token for this session
	Debug bool   // Debug for printing JSON request/responses

	// Settable Callback functions for Internal Events
	// OnConnect is called when the websocket connection opens.
	OnConnect func(*Session)
	// OnDisconnect is called when the websocket connection closes.
	// This is a good handler to add reconnection logic to.
	OnDisconnect func(*Session)

	// Settable Callback functions for Websocket Events
	OnEvent                   func(*Session, *Event)
	OnReady                   func(*Session, *Ready)
	OnTypingStart             func(*Session, *TypingStart)
	OnMessageCreate           func(*Session, *Message)
	OnMessageUpdate           func(*Session, *Message)
	OnMessageDelete           func(*Session, *Message)
	OnMessageAck              func(*Session, *MessageAck)
	OnUserUpdate              func(*Session, *User)
	OnPresenceUpdate          func(*Session, *PresenceUpdate)
	OnVoiceStateUpdate        func(*Session, *VoiceState)
	OnChannelCreate           func(*Session, *Channel)
	OnChannelUpdate           func(*Session, *Channel)
	OnChannelDelete           func(*Session, *Channel)
	OnGuildCreate             func(*Session, *Guild)
	OnGuildUpdate             func(*Session, *Guild)
	OnGuildDelete             func(*Session, *Guild)
	OnGuildMemberAdd          func(*Session, *Member)
	OnGuildMemberRemove       func(*Session, *Member)
	OnGuildMemberDelete       func(*Session, *Member)
	OnGuildMemberUpdate       func(*Session, *Member)
	OnGuildRoleCreate         func(*Session, *GuildRole)
	OnGuildRoleUpdate         func(*Session, *GuildRole)
	OnGuildRoleDelete         func(*Session, *GuildRoleDelete)
	OnGuildIntegrationsUpdate func(*Session, *GuildIntegrationsUpdate)
	OnGuildBanAdd             func(*Session, *GuildBan)
	OnGuildBanRemove          func(*Session, *GuildBan)
	OnGuildEmojisUpdate       func(*Session, *GuildEmojisUpdate)
	OnUserSettingsUpdate      func(*Session, map[string]interface{}) // TODO: Find better way?

	// Exposed but should not be modified by User.
	SessionID  string // from websocket READY packet
	DataReady  bool   // Set to true when Data Websocket is ready
	VoiceReady bool   // Set to true when Voice Websocket is ready
	UDPReady   bool   // Set to true when UDP Connection is ready

	// Stores all details related to voice connections
	Voice *Voice

	// Managed state object, updated with events.
	State        *State
	StateEnabled bool

	// Should the session reconnect the websocket on errors.
	ShouldReconnectOnError bool

	// Should the session request compressed websocket data.
	Compress bool
	// contains filtered or unexported fields
}

A Session represents a connection to the Discord REST API. token : The authentication token returned from Discord Debug : If set to ture debug logging will be displayed.

func New 

func New(args ...interface{}) (s *Session, err error)

New creates a new Discord session and will automate some startup tasks if given enough information to do so. Currently you can pass zero arguments and it will return an empty Discord session. There are 3 ways to call New: 

With a single auth token - All requests will use the token blindly,
    no verification of the token will be done and requests may fail.
With an email and password - Discord will sign in with the provided
    credentials.
With an email, password and auth token - Discord will verify the auth
    token, if it is invalid it will sign in with the provided
    credentials. This is the Discord recommended way to sign in.

func (*Session) Channel 

func (s *Session) Channel(channelID string) (st *Channel, err error)

Channel returns a Channel strucutre of a specific Channel. channelID : The ID of the Channel you want returend.

func (*Session) ChannelDelete 

func (s *Session) ChannelDelete(channelID string) (st *Channel, err error)

ChannelDelete deletes the given channel channelID : The ID of a Channel

func (*Session) ChannelEdit 

func (s *Session) ChannelEdit(channelID, name string) (st *Channel, err error)

ChannelEdit edits the given channel channelID : The ID of a Channel name : The new name to assign the channel.

func (*Session) ChannelInviteCreate 

func (s *Session) ChannelInviteCreate(channelID string, i Invite) (st *Invite, err error)

ChannelInviteCreate creates a new invite for the given channel. channelID : The ID of a Channel i : An Invite struct with the values MaxAge, MaxUses, Temporary, 

and XkcdPass defined.

func (*Session) ChannelInvites 

func (s *Session) ChannelInvites(channelID string) (st []*Invite, err error)

ChannelInvites returns an array of Invite structures for the given channel channelID : The ID of a Channel

func (*Session) ChannelMessageAck 

func (s *Session) ChannelMessageAck(channelID, messageID string) (err error)

ChannelMessageAck acknowledges and marks the given message as read channeld : The ID of a Channel messageID : the ID of a Message

func (*Session) ChannelMessageDelete 

func (s *Session) ChannelMessageDelete(channelID, messageID string) (err error)

ChannelMessageDelete deletes a message from the Channel.

func (*Session) ChannelMessageEdit 

func (s *Session) ChannelMessageEdit(channelID, messageID, content string) (st *Message, err error)

ChannelMessageEdit edits an existing message, replacing it entirely with the given content. channeld : The ID of a Channel messageID : the ID of a Message

func (*Session) ChannelMessageSend 

func (s *Session) ChannelMessageSend(channelID string, content string) (st *Message, err error)

ChannelMessageSend sends a message to the given channel. channelID : The ID of a Channel. content : The message to send. NOTE, mention and tts parameters may be added in 2.x branch.

func (*Session) ChannelMessages 

func (s *Session) ChannelMessages(channelID string, limit int, beforeID int, afterID int) (st []*Message, err error)

ChannelMessages returns an array of Message structures for messages within a given channel. channelID : The ID of a Channel. limit : The number messages that can be returned. beforeID : If provided all messages returned will be before given ID. afterID : If provided all messages returned will be after given ID.

func (*Session) ChannelPermissionDelete added in v0.7.0 

func (s *Session) ChannelPermissionDelete(channelID, targetID string) (err error)

ChannelPermissionDelete deletes a specific permission override for the given channel. NOTE: Name of this func may change.

func (*Session) ChannelPermissionSet added in v0.7.0 

func (s *Session) ChannelPermissionSet(channelID, targetID, targetType string, allow, deny int) (err error)

ChannelPermissionSet creates a Permission Override for the given channel. NOTE: This func name may changed. Using Set instead of Create because you can both create a new override or update an override with this function.

func (*Session) ChannelTyping 

func (s *Session) ChannelTyping(channelID string) (err error)

ChannelTyping broadcasts to all members that authenticated user is typing in the given channel. channelID : The ID of a Channel

func (*Session) ChannelVoiceJoin added in v0.9.0 

func (s *Session) ChannelVoiceJoin(gID, cID string, mute, deaf bool) (err error)

ChannelVoiceJoin joins the session user to a voice channel. After calling this func please monitor the Session.Voice.Ready bool to determine when it is ready and able to send/receive audio, that should happen quickly. 

gID   : Guild ID of the channel to join.
cID   : Channel ID of the channel to join.
mute  : If true, you will be set to muted upon joining.
deaf  : If true, you will be set to deafened upon joining.

func (*Session) Close 

func (s *Session) Close() (err error)

Close closes a websocket and stops all listening/heartbeat goroutines. TODO: Add support for Voice WS/UDP connections

func (*Session) Gateway 

func (s *Session) Gateway() (gateway string, err error)

Gateway returns the a websocket Gateway address

func (*Session) Guild 

func (s *Session) Guild(guildID string) (st *Guild, err error)

Guild returns a Guild structure of a specific Guild. guildID : The ID of a Guild

func (*Session) GuildBanCreate added in v0.7.0 

func (s *Session) GuildBanCreate(guildID, userID string, days int) (err error)

GuildBanCreate bans the given user from the given guild. guildID : The ID of a Guild. userID : The ID of a User days : The number of days of previous comments to delete.

func (*Session) GuildBanDelete 

func (s *Session) GuildBanDelete(guildID, userID string) (err error)

GuildBanDelete removes the given user from the guild bans guildID : The ID of a Guild. userID : The ID of a User

func (*Session) GuildBans 

func (s *Session) GuildBans(guildID string) (st []*User, err error)

GuildBans returns an array of User structures for all bans of a given guild. guildID : The ID of a Guild.

func (*Session) GuildChannelCreate 

func (s *Session) GuildChannelCreate(guildID, name, ctype string) (st *Channel, err error)

GuildChannelCreate creates a new channel in the given guild guildID : The ID of a Guild. name : Name of the channel (2-100 chars length) ctype : Tpye of the channel (voice or text)

func (*Session) GuildChannels 

func (s *Session) GuildChannels(guildID string) (st []*Channel, err error)

GuildChannels returns an array of Channel structures for all channels of a given guild. guildID : The ID of a Guild.

func (*Session) GuildCreate 

func (s *Session) GuildCreate(name string) (st *Guild, err error)

GuildCreate creates a new Guild name : A name for the Guild (2-100 characters)

func (*Session) GuildDelete 

func (s *Session) GuildDelete(guildID string) (st *Guild, err error)

GuildDelete deletes or leaves a Guild. guildID : The ID of a Guild

func (*Session) GuildEdit 

func (s *Session) GuildEdit(guildID, name string) (st *Guild, err error)

GuildEdit edits a new Guild guildID : The ID of a Guild name : A name for the Guild (2-100 characters)

func (*Session) GuildIcon added in v0.10.0 

func (s *Session) GuildIcon(guildID string) (img image.Image, err error)

GuildIcon returns an image.Image of a guild icon. guildID : The ID of a Guild.

func (*Session) GuildInviteCreate 

func (s *Session) GuildInviteCreate(guildID string, i *Invite) (st *Invite, err error)

GuildInviteCreate creates a new invite for the given guild. guildID : The ID of a Guild. i : An Invite struct with the values MaxAge, MaxUses, Temporary, 

and XkcdPass defined.

func (*Session) GuildInvites 

func (s *Session) GuildInvites(guildID string) (st []*Invite, err error)

GuildInvites returns an array of Invite structures for the given guild guildID : The ID of a Guild.

func (*Session) GuildMemberDelete 

func (s *Session) GuildMemberDelete(guildID, userID string) (err error)

GuildMemberDelete removes the given user from the given guild. guildID : The ID of a Guild. userID : The ID of a User

func (*Session) GuildRoleCreate added in v0.7.0 

func (s *Session) GuildRoleCreate(guildID string) (st *Role, err error)

GuildRoleCreate returns a new Guild Role. guildID: The ID of a Guild.

func (*Session) GuildRoleDelete added in v0.7.0 

func (s *Session) GuildRoleDelete(guildID, roleID string) (err error)

GuildRoleDelete deletes an existing role. guildID : The ID of a Guild. roleID : The ID of a Role.

func (*Session) GuildRoleEdit added in v0.7.0 

func (s *Session) GuildRoleEdit(guildID, roleID, name string, color int, hoist bool, perm int) (st *Role, err error)

GuildRoleEdit updates an existing Guild Role with new values guildID : The ID of a Guild. roleID : The ID of a Role. name : The name of the Role. color : The color of the role (decimal, not hex). hoist : Whether to display the role's users separately. perm : The permissions for the role.

func (*Session) GuildRoleReorder added in v0.7.0 

func (s *Session) GuildRoleReorder(guildID string, roles []*Role) (st []*Role, err error)

GuildRoleReorder reoders guild roles guildID : The ID of a Guild. roles : A list of ordered roles.

func (*Session) GuildRoles added in v0.7.0 

func (s *Session) GuildRoles(guildID string) (st []*Role, err error)

GuildRoles returns all roles for a given guild. guildID : The ID of a Guild.

func (*Session) GuildSplash added in v0.10.0 

func (s *Session) GuildSplash(guildID string) (img image.Image, err error)

GuildSplash returns an image.Image of a guild splash image. guildID : The ID of a Guild.

func (*Session) Invite 

func (s *Session) Invite(inviteID string) (st *Invite, err error)

Invite returns an Invite structure of the given invite inviteID : The invite code (or maybe xkcdpass?)

func (*Session) InviteAccept 

func (s *Session) InviteAccept(inviteID string) (st *Invite, err error)

InviteAccept accepts an Invite to a Guild or Channel inviteID : The invite code (or maybe xkcdpass?)

func (*Session) InviteDelete 

func (s *Session) InviteDelete(inviteID string) (st *Invite, err error)

InviteDelete deletes an existing invite inviteID : the code (or maybe xkcdpass?) of an invite

func (*Session) Login 

func (s *Session) Login(email, password string) (err error)

Login asks the Discord server for an authentication token.

func (*Session) Logout 

func (s *Session) Logout() (err error)

Logout sends a logout request to Discord. This does not seem to actually invalidate the token. So you can still make API calls even after a Logout. So, it seems almost pointless to even use.

func (*Session) Open 

func (s *Session) Open() (err error)

Open opens a websocket connection to Discord.

func (*Session) Register added in v0.9.0 

func (s *Session) Register(username string) (token string, err error)

Register sends a Register request to Discord, and returns the authentication token Note that this account is temporary and should be verified for future use. Another option is to save the authentication token external, but this isn't recommended.

func (*Session) Request 

func (s *Session) Request(method, urlStr string, data interface{}) (response []byte, err error)

Request makes a (GET/POST/...) Requests to Discord REST API. All the other Discord REST Calls in this file use this function.

func (*Session) UpdateStatus 

func (s *Session) UpdateStatus(idle int, game string) (err error)

UpdateStatus is used to update the authenticated user's status. If idle>0 then set status to idle. If game>0 then set game. if otherwise, set status to active, and no game.

func (*Session) User 

func (s *Session) User(userID string) (st *User, err error)

User returns the user details of the given userID userID : A user ID or "@me" which is a shortcut of current user ID

func (*Session) UserAvatar 

func (s *Session) UserAvatar(userID string) (img image.Image, err error)

UserAvatar returns an image.Image of a users Avatar. userID : A user ID or "@me" which is a shortcut of current user ID

func (*Session) UserChannelCreate 

func (s *Session) UserChannelCreate(recipientID string) (st *Channel, err error)

UserChannelCreate creates a new User (Private) Channel with another User recipientID : A user ID for the user to which this channel is opened with.

func (*Session) UserChannels 

func (s *Session) UserChannels() (st []*Channel, err error)

UserChannels returns an array of Channel structures for all private channels.

func (*Session) UserGuilds 

func (s *Session) UserGuilds() (st []*Guild, err error)

UserGuilds returns an array of Guild structures for all guilds.

func (*Session) UserSettings 

func (s *Session) UserSettings() (st *Settings, err error)

UserSettings returns the settings for a given user

func (*Session) UserUpdate added in v0.6.0 

func (s *Session) UserUpdate(email, password, username, avatar, newPassword string) (st *User, err error)

UserUpdate updates a users settings.

func (*Session) VoiceICE 

func (s *Session) VoiceICE() (st *VoiceICE, err error)

VoiceICE returns the voice server ICE information

func (*Session) VoiceRegions 

func (s *Session) VoiceRegions() (st []*VoiceRegion, err error)

VoiceRegions returns the voice server regions

type Settings 

type Settings struct {
	RenderEmbeds          bool     `json:"render_embeds"`
	InlineEmbedMedia      bool     `json:"inline_embed_media"`
	EnableTtsCommand      bool     `json:"enable_tts_command"`
	MessageDisplayCompact bool     `json:"message_display_compact"`
	Locale                string   `json:"locale"`
	ShowCurrentGame       bool     `json:"show_current_game"`
	Theme                 string   `json:"theme"`
	MutedChannels         []string `json:"muted_channels"`
}

A Settings stores data for a specific users Discord client settings.

type State added in v0.8.0 

type State struct {
	sync.RWMutex
	Ready
	MaxMessageCount int
}

A State contains the current known state. As discord sends this in a READY blob, it seems reasonable to simply use that struct as the data store.

func NewState added in v0.8.0 

func NewState() *State

NewState creates an empty state.

func (*State) Channel added in v0.8.0 

func (s *State) Channel(channelID string) (*Channel, error)

Channel gets a channel by ID, it will look in all guilds an private channels.

func (*State) ChannelAdd added in v0.8.0 

func (s *State) ChannelAdd(channel *Channel) error

ChannelAdd adds a guild to the current world state, or updates it if it already exists. Channels may exist either as PrivateChannels or inside a guild.

func (*State) ChannelRemove added in v0.8.0 

func (s *State) ChannelRemove(channel *Channel) error

ChannelRemove removes a channel from current world state.

func (*State) Emoji added in v0.8.0 

func (s *State) Emoji(guildID, emojiID string) (*Emoji, error)

Emoji returns an emoji for a guild and emoji id.

func (*State) EmojiAdd added in v0.8.0 

func (s *State) EmojiAdd(guildID string, emoji *Emoji) error

EmojiAdd adds an emoji to the current world state.

func (*State) EmojisAdd added in v0.8.0 

func (s *State) EmojisAdd(guildID string, emojis []*Emoji) error

EmojisAdd adds multiple emojis to the world state.

func (*State) Guild added in v0.8.0 

func (s *State) Guild(guildID string) (*Guild, error)

Guild gets a guild by ID. Useful for querying if @me is in a guild: 

_, err := discordgo.Session.State.Guild(guildID)
isInGuild := err == nil

func (*State) GuildAdd added in v0.8.0 

func (s *State) GuildAdd(guild *Guild) error

GuildAdd adds a guild to the current world state, or updates it if it already exists.

func (*State) GuildChannel added in v0.8.0 

func (s *State) GuildChannel(guildID, channelID string) (*Channel, error)

GuildChannel gets a channel by ID from a guild.

func (*State) GuildRemove added in v0.8.0 

func (s *State) GuildRemove(guild *Guild) error

GuildRemove removes a guild from current world state.

func (*State) Member added in v0.8.0 

func (s *State) Member(guildID, userID string) (*Member, error)

Member gets a member by ID from a guild.

func (*State) MemberAdd added in v0.8.0 

func (s *State) MemberAdd(member *Member) error

MemberAdd adds a member to the current world state, or updates it if it already exists.

func (*State) MemberRemove added in v0.8.0 

func (s *State) MemberRemove(member *Member) error

MemberRemove removes a member from current world state.

func (*State) Message added in v0.10.0 

func (s *State) Message(channelID, messageID string) (*Message, error)

Message gets a message by channel and message ID.

func (*State) MessageAdd added in v0.10.0 

func (s *State) MessageAdd(message *Message) error

MessageAdd adds a message to the current world state, or updates it if it exists. If the channel cannot be found, the message is discarded. Messages are kept in state up to s.MaxMessageCount

func (*State) MessageRemove added in v0.10.0 

func (s *State) MessageRemove(message *Message) error

MessageRemove removes a message from the world state.

func (*State) OnReady added in v0.8.0 

func (s *State) OnReady(r *Ready) error

OnReady takes a Ready event and updates all internal state.

func (*State) PrivateChannel added in v0.8.0 

func (s *State) PrivateChannel(channelID string) (*Channel, error)

PrivateChannel gets a private channel by ID.

type TypingStart 

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

A TypingStart stores data for the typing start websocket event.

type User 

type User struct {
	ID       string `json:"id"`
	Email    string `json:"email"`
	Username string `json:"username"`
	Avatar   string `json:"Avatar"`
	Verified bool   `json:"verified"`
}

A User stores all data for an individual Discord user.

type Voice added in v0.9.0 

type Voice struct {
	sync.Mutex             // future use
	Ready      bool        // If true, voice is ready to send/receive audio
	Debug      bool        // If true, print extra logging
	OP2        *voiceOP2   // exported for dgvoice, may change.
	Opus       chan []byte // Chan for sending opus audio

	UDPConn *net.UDPConn // this will become unexported soon.
	// contains filtered or unexported fields
}

A Voice struct holds all data and functions related to Discord Voice support.

func (*Voice) Close added in v0.9.0 

func (v *Voice) Close()

Close closes the voice connection

func (*Voice) Open added in v0.9.0 

func (v *Voice) Open() (err error)

Open opens a voice connection. This should be called after VoiceChannelJoin is used and the data VOICE websocket events are captured.

func (*Voice) Speaking added in v0.9.0 

func (v *Voice) Speaking(b bool) (err error)

Speaking sends a speaking notification to Discord over the voice websocket. This must be sent as true prior to sending audio and should be set to false once finished sending audio. 

b  : Send true if speaking, false if not.

type VoiceICE 

type VoiceICE struct {
	TTL     string       `json:"ttl"`
	Servers []*ICEServer `json:"servers"`
}

A VoiceICE stores data for voice ICE servers.

type VoiceRegion 

type VoiceRegion struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Hostname string `json:"sample_hostname"`
	Port     int    `json:"sample_port"`
}

A VoiceRegion stores data for a specific voice region server.

type VoiceServerUpdate 

type VoiceServerUpdate struct {
	Token    string `json:"token"`
	GuildID  string `json:"guild_id"`
	Endpoint string `json:"endpoint"`
}

A VoiceServerUpdate stores the data received during the Voice Server Update data websocket event. This data is used during the initial Voice Channel join handshaking.

type VoiceState 

type VoiceState struct {
	UserID    string `json:"user_id"`
	Suppress  bool   `json:"suppress"`
	SessionID string `json:"session_id"`
	SelfMute  bool   `json:"self_mute"`
	SelfDeaf  bool   `json:"self_deaf"`
	Mute      bool   `json:"mute"`
	Deaf      bool   `json:"deaf"`
	ChannelID string `json:"channel_id"`
}

A VoiceState stores the voice states of Guilds

Source Files

View all Source files

Directories

Path Synopsis
examples
api_basic
This file provides a basic "quick start" example of using the Discordgo package to connect to Discord using the low level API functions.
 This file provides a basic "quick start" example of using the Discordgo package to connect to Discord using the low level API functions.
new_basic
This file provides a basic "quick start" example of using the Discordgo package to connect to Discord using the New() helper function.
 This file provides a basic "quick start" example of using the Discordgo package to connect to Discord using the New() helper function.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.