bwmarrin / discordgo

(Golang) Go bindings for Discord

DiscordGo

DiscordGo is a Go package that provides low level bindings to the Discord chat client API. DiscordGo has nearly complete support for all of the Discord API endpoints, websocket interface, and voice interface.

If you would like to help the DiscordGo package please use this link to add the official DiscordGo test bot dgo to your server. This provides indispensable help to this project.

• See dgVoice package for an example of additional voice helper functions and features for DiscordGo.

• See dca for an experimental stand alone tool that wraps ffmpeg to create opus encoded audio appropriate for use with Discord (and DiscordGo).

For help with this package or general Go discussion, please join the Discord Gophers chat server.

Getting Started

Installing

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

go get will always pull the latest tagged release from the master branch.

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("Bot " + "authentication token")

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 in the future.

The DiscordGo code is fairly well documented at this point and is currently the only documentation available. Go reference (below) presents that information in a nice format.

• 
• Hand crafted documentation coming eventually.

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.

• DiscordGo Examples - A collection of example programs written with DiscordGo
• Awesome DiscordGo - A curated list of high quality projects using DiscordGo

Troubleshooting

For help with common problems please reference the Troubleshooting section of the project wiki.

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.
• 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 master branch.

List of Discord APIs

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

Special Thanks

Chris Rhodes - For the DiscordGo logo and tons of PRs.

discordgo's Issues

Add support for ws event REDIRECT

Make websocket Heartbeat func to only start if not started.

If, by accident, two websocket heartbeat's get started then Discord will close the websocket connection abruptly. Need to modify the function to just ignore any requests to start a second heartbeat.

Add checks when opening Voice & UDP

VoiceChannelJoin right now calls code to open both new voice websocket and udp connection. But once those are open they should ignore requests. Allowing the bot/client to join different voice channels. Might need to still do some checking for channels on different guilds/servers because they should require a separate connection.

REST API Rate Limit

Add variables for enable/disable, bucket fillrate, and bucket size. Auto adjust these rates based on HTTP 429 responses from Discord. Might need a general limit, and a per request type limit.

For this to work with concurrency, create buffered channel's and have a "filler" process add to the channels. Then the REST API Request() func can take from the channels on each request and block if a channel is empty.

Proper error logging

Right now most logging is done with fmt.Print... but this needs changed to something more proper.

Cache Auth Token

Discord Devs would like libs to cache the auth token because the login endpoint is expensive. Right now DiscordGo already keeps the token in memory while it's running so we only need a way to store that token so it can be used during restarts.

Improve restapi.go Request func

• User-Agent is missing closing parenthesis
• Needs improved logging if debug is enabled
• Improve Status Code checking, add initial code for supporting 401/429 codes.

Use structs for all JSON data sent to Discord

Some parts of the library are using either interface map or strings for json data sent to Discord. This must be changed so that everything goes though an anonymous struct then marshaled properly and send to Discord.

Cannot compile package on Debian 8 or with Go 1.3

Debian 8 comes with Go 1.3 and when installing the Discordgo package or attempting to compile it on Debian 8 you received the below error message.

# github.com/bwmarrin/discordgo
./voice.go:302: syntax error: unexpected range, expecting {
./voice.go:319: syntax error: unexpected }

Also, the below error appears once the above is resolved.

# github.com/bwmarrin/discordgo
./restapi.go:159: undefined: json.Token

Add support for sending presence info

Need to add into data websocket layer a function for sending presence info for the authenticated user.

Gorilla websocket concurrency

Per docs,

Connections support one concurrent reader and one concurrent writer.

Applications are responsible for ensuring that no more than one goroutine calls the write methods (NextWriter, SetWriteDeadline, WriteMessage, WriteJSON) concurrently and that no more than one goroutine calls the read methods (NextReader, SetReadDeadline, ReadMessage, ReadJSON, SetPongHandler, SetPingHandler) concurrently.

The Close and WriteControl methods can be called concurrently with all other methods.

Need to setup a way to make sure this is done correctly in DiscrodGo

Add support for mentions to ChannelMessageSend function

Need to enhance the ChannelMessageSend function to support mentions.

Remove /guilds/:guild_id/members endpoint

Per React, /guilds/:guild_id/members endpoint is being removed.

Add support for editing profile

Need to add support for editing the authenticated user's profile

Add support for channel permissions

Need to add support for the management of channel permissions.

Support gateway redirects

Stan says:

Just so you guys know probably within a week there will be a major real-time system change to Discord.
the /gateway call will need the auth token because gateways will be assigned around a consistent hash ring
If you conncet to the wrong gateway it will send you a redirect opcode with the URL to the correct one
But the easiest way to be ready for this is to just send the auth token to /api/gateway and then you dont need to worry about it
But the redirect opcode can be also fired if the servers rebalance
but doubt that will be happening for a bit after the upgrade
its special cause gateways support resuming a session id
instead of identify you send a resume
with the previous session id
and it keeps going on the new node
This way we can seamless move people between gateways during DDoS or just scale up 😃
also works for timeouts (aka cloudflare issue)
opcode is 7
and the data is just
{"url": "new websocket url here"}
If you want to support resuming a session you need to keep the session_id in your websocket instance.. and also keep track of the 's' variable aka seq on events (keep last one)
and when you try reconnect after a DC or a redirect
send opcode 6 with {'session_id': session_id, 'seq': seq}
instead of identify
every message will have a seq
's'
keep the last one

Make voice support within main library stable.

Right now the voice support in the main library is still marked as experimental. I need to review and test the code that is currently part of the main library and make changes as needed so it is no longer considered experimental.

GuildBanAdd should be renamed

In order to match the wording used for other functions, GuildBanAdd should be renamed to GuildBanCreate.

Make changes to match how Discord now sends Game playing status.

Game Change Updates

The currently playing game information in the presence updates is changing today. The game information will be contained in an object contained at the game key. This value will either be null (no game is being played) or an object with the key name, which has the currently playing game name. {"name": "World of Warcraft"}

This change means that game_id no longer exists. Instead, it is being changed to game which is either an object or null. The object only contains the game name.(edited)

• React/Jake

Complete voice support for sending audio

Right now, there is an experimental sister package that provides basic support for sending audio files. This needs to be reviewed and modified as needed so it can be considered stable.

Add support for message embeds

Currently Message embeds are not kept. Need to create the proper struct for them so they can be used.

Add support for message attachments

Currently Message attachments are not kept. Need to create the proper struct for them so they can be used.

Reconnect flag & feature

Library needs a configurable flag to reconnect on any unexpected disconnects. This needs some logic to keep it from running wild, maybe a max reconnect of X with a Y delay between attempts.

Add support for role management

Need to add support for the management of roles

Add support for events GUILD_BAN_ADD and GUILD_BAN_REMOVE

Add support for receiving audio/voice

Right now there is only partial, experimental, support for receiving audio. This needs to be reviewed and completed.

Add "Ready" bools to Session

Session needs Ready bools so end-user knows when channels/connections are ready for use. Like DataReady for data websocket, VoiceReady for voice websocket, UDPReady for the UDP connection.

Add support for ws event GUILD_MEMBERS_CHUNK

Add support for Discord maintenance status api

Clean up voice VoiceOpenUDP func

This func has some hackish code that will not work on all IP address. Use a for loop to get entire (up to 15 bytes) of IP address. Adjust method for getting port so we don't require a second variable declaration that isn't needed.

If user doesn't handle READY, do it for them.

If the client or user of the package doesn't register a function for the OnReady event. Go ahead and do basic handling of that event and fire off the websocket heartbeat.

Include library/path to github User-Agent

hey api library devs - can you all include your library/path to github in your User-Agent? -- React

Add support for registering a new account.

The Register endpoint is already defined but need to create a function to interact with it.

Manage goroutines better.

I fire off a few goroutines but all of these need to have code added to monitor and control them. Need to track what goroutines are running and ability to tell them to shut down. Heartbeats and websocket listen goroutines for example.

Add support for receiving audio.

Need to add support for receiving audio.

Incorrect handling of WSAPI errors

et Listen Error read tcp 10.1.10.17:49656->45.79.158.60:443: wsarecv: A connection attempt failed because the con
nected party did not properly respond after a period of time, or established connection failed because connected host ha
s failed to respond.
panic: close of nil channel

goroutine 39 [running]:
github.com/iopred/discordgo.(*Session).Listen(0xc0821ea1e0, 0x0, 0x0)
D:/Documents/Go/src/github.com/iopred/discordgo/wsapi.go:133 +0x3ed
created by github.com/iopred/discordgo.New
D:/Documents/Go/src/github.com/iopred/discordgo/discord.go:115 +0x652

Enhance websocket close logging

Need to improve the logging done when a websocket closes so that it includes any message provided by Discord to explain the log which would be in the message body.

Basic Validation on all functions needed

Some functions require specific things to have already happened. Such as a valid data or voice websocket connection or UDP connection. All of these functions should validate that these things exist before trying to act upon them.

Add handler for USER_SETTINGS_UPDATE websocket event

USER_SETTINGS_UPDATE support needs to be added.

Add tests for majority of package funcs.

We should have tests for as many funcs as is possible.

Add support for large_threshold

Setting large_threshold: 100 or .. X number limits the number of offline users that are sent with the READY packet. Should implement a way for users to define this in a variable of some sort :)

Add support for ws event RESUMED

Fix logout function

Logout func never was converted to use proper structs and is still commented out. Needs to be fixed :)

Clean up Audio Send

Right now sending audio is mostly experimental. All of that code needs more review and lots of clean up to make it less-experimental :)

Create tests for all exposed functions

Need to write a program that tests all exposed functions at some basic level.

Add support for compressed websocket packets

"send compressed: true in your Connect info,
have your Accept-Encode headers set to gzip and deflate
if the READY event is big enough, it'll be sent as compressed binary data
just decompress it and move the bytes to a string"

Add support for ws event USER_UPDATE

Finalize API

The API is still in a bit of a flux and needs to be finalized at some point before we can issue a 1.0.0 release. I am open to thoughts on this to help decide the best way to accomplish this goal. See below :)

• Function names to closely match whatever Discord itself calls something as well as match the Discord endpoint used by the function.
• Functions should be named in the format of CategoryAction so GuildAdd instead of AddGuild.
• Functions should be named without a trailing s when only one item is returned: Guild(id) vs Guilds(id). however if it returns an array it should contain the trailing s: UserGuilds() vs UserGuild()

The way that our main Struct is laid out is the main point where I'm open to discussion.

Currently, pretty much everything is just thrown into the big Session{} struct. On one hand that makes it so we don't have overly long names when accessing things. On the other hand, we have one big messy struct with dozens of funcs, variables, etc. Also it makes it harder to have consistent naming in some cases.

The other idea is that we split up the package into categories of concerns. As I see it right now we could possibly have 3 separate categories:

• HTTP Endpoints (restapi.go)
• "Data" Websocket (wsapi.go)
• Voice (voice.go) -- has both Voice.WS and Voice.UDP as sub-concerns.

The HTTP Endpoints and Data Websocket could possible be paired together in some fashion or make entirely separate.

The idea is that you would have commands, such as

Right now I've been working on the Voice struct since it's not used much and I feel better about changing it. The direction I am going would create commands like.

Discord.Voice.WS.Open()
Discord.Voice.WS.Heartbeat()
Discord.Voice.WS.Ready   // bool
Discord.Voice.WS.Listen()

Discord.Voice.UDP.Open()
Discord.Voice.UDP.Heartbeat()
Discord.Voice.UDP.Ready  // bool
Discord.Voice.UDP.Listen()

And so on, this lets me use the same names for a lot of things but have them separated into their own structs.

PLEASE Comment with ideas. This is my first API package so I might be looking at this all wrong.

Calls to Login func with invalid email/password crash.

Login func should return an error instead of crashing the entire application when called with an invalid username or password :)

Add support for delete-message-days=x on bans endpoint