Index
DiscordGo
<hr>
<img align="right" src="https://github.com/bwmarrin/discordgo/blob/master/docs/img/discordgo.png">
Go (Golang) interface for the Discord
chat service. Provides both low-level direct bindings to the
Discord API and helper functions that allow you to make custom clients and chat
bot applications easily.
Discord is an all-in-one voice and text chat for
gamers that's free, secure, and works on both your desktop and phone.
Why DiscordGo?
* High Performance
* Minimal Memory & CPU Load
* Low-level bindings to Discord REST API Endpoints
* Support for the data websocket interface
* Multi-Server voice connections (send and receive)
* State tracking and caching
Learn More
* Check out the Getting Started section
* Read the reference docs on Godoc or GoWalker
* Try the examples
* Explore Awesome DiscordGo
Join Us!
Both of the below links take you to chat channels where you can get more
information and support for DiscordGo. There's also a chance to make some
friends :).
* Join the Discord Gophers chat server dedicated to Go programming.
* Join the Discord API chat server dedicated to the Discord API.
---
GettingStarted
Getting Started
This page is dedicated to helping you get started on your way to making the
next great Discord bot or client with DiscordGo. Once you've done that please
don't forget to submit it to the
Awesome DiscordGo list :).
First, lets cover a few topics so you can make the best choices on how to
move forward from here.
#### Bot Application
A bot application is a special program that interacts with the Discord servers
to perform some form of automation or provide some type of service. Examples
are things like number trivia games, music streaming, channel moderation,
sending reminders, playing loud airhorn sounds, comic generators, YouTube
integration, Twitch integration... You're almost only limited by your imagination.
Bot applications require the use of a special Bot account. These accounts are
tied to your personal user account. Bot accounts cannot login with the normal
user clients and they cannot join servers the same way a user does. They do not
have access to some user client specific features however they gain access to
many Bot specific features.
To create a new bot account first create yourself a normal user account on
Discord then visit the My Applications
page and click on the New Application box. Follow the prompts from there
to finish creating your account.
More information about Bot vs Client accounts can be found here.
Requirements
DiscordGo requires Go version 1.4 or higher. It has been tested to compile and
run successfully on Debian Linux 8, FreeBSD 10, and Windows 7. It is expected
that it should work anywhere Go 1.4 or higher works. If you run into problems
please let us know :).
You must already have a working Go environment setup to use DiscordGo. If you
are new to Go and have not yet installed and tested it on your computer then
please visit this page first then I highly
recommend you walk though A Tour of Go to
help get your familiar with the Go language. Also checkout the relevant Go plugin
for your editor — they are hugely helpful when developing Go code.
* Vim — vim-go
* Sublime — GoSublime
* Atom — go-plus
* Visual Studio — vscode-go
Install DiscordGo
Like any other Go package the fist step is to go get the package. This will
always pull the latest tagged release from the master branch. Then run go install to compile and install the libraries on your system.
#### Linux/BSD
Run go get to download the package to your GOPATH/src folder.
go get github.com/bwmarrin/discordgoFinally, compile and install the package into the GOPATH/pkg folder. This isn't
absolutely required but doing this will allow the Go plugin for your editor to
provide autocomplete for all DiscordGo functions.
cd $GOPATH/src/github.com/bwmarrin/discordgo
go install#### Windows
Placeholder.
Next...
More coming soon.
---
CONTRIBUTING
Getting started
To start off you can check out existing Pull Requests and Issues to get a gasp of what problems we’re currently solving and what features you can implement.
Issues
Our issues are mostly used for bugs, however we welcome refactoring and conceptual issues.
Any other conversation would belong and would be moved into “Discussions”.
Discussions
We use discussions for ideas, polls, announcements and help questions.
Don’t hesitate to ask, we always would try to help.
Pull Requests
If you want to help us by improving existing or adding new features, you create what’s called a Pull Request (aka PR). It allows us to review your code, suggest changes and merge it.
Here are some tips on how to make a good first PR:
- When creating a PR, please consider a distinctive name and description for it, so the maintainers can understand what your PR changes / adds / removes.
- It’s always a good idea to link documentation when implementing a new feature / endpoint
- If you’re resolving an issue, don’t forget to link it in the description.
- Enable the checkbox to allow maintainers to edit your PR and make commits in the PR branch when necessary.
- We may ask for changes, usually through suggestions or pull request comments. You can apply suggestions right in the UI. Any other change needs to be done manually.
- Don’t forget to mark PR comments resolved when you’re done applying the changes.
- Be patient and don’t close and reopen your PR when no one responds, sometimes it might be held for a while. There might be a lot of reasons: release preparation, the feature is not significant, maintainers are busy, etc.
When your changes are still incomplete (i.e. in Work In Progress state), you can still create a PR, but consider making it a draft.
To make a draft PR, you can change the type of PR by clicking to a triangle next to the “Create Pull Request” button.
Once you’re done, you can mark it as “Ready for review”, and we’ll get right on it.
Code style
To standardize and make things less messy we have a certain code style, that is persistent throughout the codebase.
Naming
REST methods
When naming a REST method, while it might seem counterintuitive, we specify the entity before the action verb (for GET endpoints we don’t specify one however). Here’s an example:
Endpoint name: Get Channel Message
> Method name: ChannelMessageEndpoint name: Edit Channel Message
> Method name: ChannelMessageEditParameter structures
When making a complex REST endpoint, sometimes you might need to implement a Param structure. This structure contains parameters for certain endpoint/set of endpoints.
- If an endpoint/set of endpoints have mostly same parameters, it’s a good idea to use a single Param structure for them. Here’s an example:
> Endpoint: GuildMemberEdit
>
> Param structure: GuildMemberParams
- If an endpoint/set of endpoints have differentiating parameters, Param structure can be named after the endpoint’s verb. Here’s an example:
> Endpoint: ChannelMessageSendComplex
>
> Param structure: MessageSend
> Endpoint: ChannelMessageEditComplex
>
> Param structure: MessageEdit
Events
When naming an event, we follow gateway’s internal naming (which often matches with the official event name in the docs). Here’s an example:
Event name: Interaction Create (INTERACTION_CREATE)> Structure name: InteractionCreateReturns
In our REST functions we usually favor named returns instead of regular anonymous returns. This helps readability.
Additionally we try to avoid naked return statements for functions with a long body. Since it’s easier to loose track of the return result.
---
README
DiscordGo
[](https://pkg.go.dev/github.com/bwmarrin/discordgo) [](https://goreportcard.com/report/github.com/bwmarrin/discordgo) [](https://github.com/bwmarrin/discordgo/actions/workflows/ci.yml) [](https://discord.gg/golang) [](https://discord.com/invite/discord-api)
<img align="right" alt="DiscordGo logo" src="docs/img/discordgo.svg" width="400">
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/discordgoUsage
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.
- [](https://pkg.go.dev/github.com/bwmarrin/discordgo)
- 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.
---
Mkdocs.Yml
site_name: DiscordGo
site_author: Bruce Marriner
site_url: http://bwmarrin.github.io/discordgo/
repo_url: https://github.com/bwmarrin/discordgo
dev_addr: 0.0.0.0:8000
theme: yeti
markdown_extensions:
- smarty
- toc:
permalink: True
- sane_lists
pages:
- 'Home': 'index.md'
- 'Getting Started': 'GettingStarted.md'
---