### Index

## DiscordGo
<hr>
<img align="right" src="https://github.com/bwmarrin/discordgo/blob/master/docs/img/discordgo.png">

[Go](https://golang.org/) (Golang) interface for the [Discord](https://discord.com/) 
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](https://discord.com/) 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](GettingStarted.md) section
* Read the reference docs on [Godoc](https://godoc.org/github.com/bwmarrin/discordgo) or [GoWalker](https://gowalker.org/github.com/bwmarrin/discordgo)
* Try the [examples](https://github.com/bwmarrin/discordgo/tree/master/examples)
* Explore [Awesome DiscordGo](https://github.com/bwmarrin/discordgo/wiki/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](https://discord.gg/0f1SbxBZjYoCtNPP) chat server dedicated to Go programming.
* Join the [Discord API](https://discord.com/invite/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](https://github.com/bwmarrin/discordgo/wiki/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](https://discord.com/developers/applications/me)
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](https://discord.com/developers/docs/topics/oauth2#bot-vs-user-accounts).**

# 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](https://golang.org/doc/install) first then I highly
recommend you walk though [A Tour of Go](https://tour.golang.org/welcome/1) to
help get your familiar with the Go language.  Also checkout the relevant Go plugin 
for your editor &mdash; they are hugely helpful when developing Go code.

* Vim &mdash; [vim-go](https://github.com/fatih/vim-go)
* Sublime &mdash; [GoSublime](https://github.com/DisposaBoy/GoSublime)
* Atom &mdash; [go-plus](https://atom.io/packages/go-plus)
* Visual Studio &mdash; [vscode-go](https://github.com/Microsoft/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.

```sh
go get github.com/bwmarrin/discordgo
```

Finally, 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.

```sh
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](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) 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: `ChannelMessage`

> Endpoint name: Edit Channel Message
>
> Method name: `ChannelMessageEdit`

### Parameter 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: `InteractionCreate`

## Returns

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](https://golang.org/) package that provides low level 
bindings to the [Discord](https://discord.com/) 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](https://discord.com/oauth2/authorize?client_id=173113690092994561&scope=bot)
to add the official DiscordGo test bot **dgo** to your server. This provides 
indispensable help to this project.

* See [dgVoice](https://github.com/bwmarrin/dgvoice) package for an example of
additional voice helper functions and features for DiscordGo.

* See [dca](https://github.com/bwmarrin/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](https://discord.gg/golang) chat server.**

## Getting Started

### Installing

This assumes you already have a working Go environment, if not please see
[this page](https://golang.org/doc/install) first.

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

```sh
go get github.com/bwmarrin/discordgo
```

### Usage

Import the package into your project.

```go
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.

```go
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](https://github.com/bwmarrin/discordgo/tree/master/examples) - A collection of example programs written with DiscordGo
- [Awesome DiscordGo](https://github.com/bwmarrin/discordgo/wiki/Awesome-DiscordGo) - A curated list of high quality projects using DiscordGo

## Troubleshooting
For help with common problems please reference the 
[Troubleshooting](https://github.com/bwmarrin/discordgo/wiki/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](https://abal.moe/Discord/Libraries.html) for a feature 
comparison and list of other Discord API libraries.

## Special Thanks

[Chris Rhodes](https://github.com/iopred) - 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'

---