README.md
1# DiscordGo
2
3[](https://godoc.org/github.com/bwmarrin/discordgo) [](http://goreportcard.com/report/bwmarrin/discordgo) [](https://travis-ci.org/bwmarrin/discordgo) [](https://discord.gg/0f1SbxBZjYoCtNPP) [](https://discord.gg/0SBTUU1wZTWT6sqd)
4
5<img align="right" src="http://bwmarrin.github.io/discordgo/img/discordgo.png">
6
7DiscordGo is a [Go](https://golang.org/) package that provides low level
8bindings to the [Discord](https://discordapp.com/) chat client API. DiscordGo
9has nearly complete support for all of the Discord API endpoints, websocket
10interface, and voice interface.
11
12If you would like to help the DiscordGo package please use
13[this link](https://discordapp.com/oauth2/authorize?client_id=173113690092994561&scope=bot)
14to add the official DiscordGo test bot **dgo** to your server. This provides
15indispensable help to this project.
16
17* See [dgVoice](https://github.com/bwmarrin/dgvoice) package for an example of
18additional voice helper functions and features for DiscordGo.
19
20* See [dca](https://github.com/bwmarrin/dca) for an **experimental** stand alone
21tool that wraps `ffmpeg` to create opus encoded audio appropriate for use with
22Discord (and DiscordGo).
23
24**For help with this package or general Go discussion, please join the [Discord
25Gophers](https://discord.gg/0f1SbxBZjYq9jLBk) chat server.**
26
27## Getting Started
28
29### master vs develop Branch
30* The master branch represents the latest released version of DiscordGo. This
31branch will always have a stable and tested version of the library. Each release
32is tagged and you can easily download a specific release and view release notes
33on the github [releases](https://github.com/bwmarrin/discordgo/releases) page.
34
35* The develop branch is where all development happens and almost always has
36new features over the master branch. However breaking changes are frequently
37added to develop and even sometimes bugs are introduced. Bugs get fixed and
38the breaking changes get documented before pushing to master.
39
40*So, what should you use?*
41
42If you can accept the constant changing nature of *develop*, it is the
43recommended branch to use. Otherwise, if you want to tail behind development
44slightly and have a more stable package with documented releases, use *master*.
45
46### Installing
47
48This assumes you already have a working Go environment, if not please see
49[this page](https://golang.org/doc/install) first.
50
51`go get` *will always pull the latest released version from the master branch.*
52
53```sh
54go get github.com/bwmarrin/discordgo
55```
56
57If you want to use the develop branch, follow these steps next.
58
59```sh
60cd $GOPATH/src/github.com/bwmarrin/discordgo
61git checkout develop
62```
63
64### Usage
65
66Import the package into your project.
67
68```go
69import "github.com/bwmarrin/discordgo"
70```
71
72Construct a new Discord client which can be used to access the variety of
73Discord API functions and to set callback functions for Discord events.
74
75```go
76discord, err := discordgo.New("Bot " + "authentication token")
77```
78
79See Documentation and Examples below for more detailed information.
80
81
82## Documentation
83
84**NOTICE** : This library and the Discord API are unfinished.
85Because of that there may be major changes to library in the future.
86
87The DiscordGo code is fairly well documented at this point and is currently
88the only documentation available. Both GoDoc and GoWalker (below) present
89that information in a nice format.
90
91- [](https://godoc.org/github.com/bwmarrin/discordgo)
92- [](https://gowalker.org/github.com/bwmarrin/discordgo)
93- Hand crafted documentation coming eventually.
94
95
96## Examples
97
98Below is a list of examples and other projects using DiscordGo. Please submit
99an issue if you would like your project added or removed from this list.
100
101- [DiscordGo Examples](https://github.com/bwmarrin/discordgo/tree/master/examples) - A collection of example programs written with DiscordGo
102- [Awesome DiscordGo](https://github.com/bwmarrin/discordgo/wiki/Awesome-DiscordGo) - A curated list of high quality projects using DiscordGo
103
104## Troubleshooting
105For help with common problems please reference the
106[Troubleshooting](https://github.com/bwmarrin/discordgo/wiki/Troubleshooting)
107section of the project wiki.
108
109
110## Contributing
111Contributions are very welcomed, however please follow the below guidelines.
112
113- First open an issue describing the bug or enhancement so it can be
114discussed.
115- Fork the develop branch and make your changes.
116- Try to match current naming conventions as closely as possible.
117- This package is intended to be a low level direct mapping of the Discord API,
118so please avoid adding enhancements outside of that scope without first
119discussing it.
120- Create a Pull Request with your changes against the develop branch.
121
122
123## List of Discord APIs
124
125See [this chart](https://abal.moe/Discord/Libraries.html) for a feature
126comparison and list of other Discord API libraries.
127
128## Special Thanks
129
130[Chris Rhodes](https://github.com/iopred) - For the DiscordGo logo and tons of PRs.
131
){kind=link}
){kind=link}
){kind=link}
){kind=link}
