Skip to content
Harmony is a peaceful Go module for interacting with Discord's API
Go
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update issue templates Oct 16, 2019
_scripts Remove self bot support (#27) Feb 9, 2019
audit Add support for querying guild audit log (#31) Jul 1, 2019
channel Update channel and message types (#47) Oct 26, 2019
debug Rename project from Discord to Harmony (#7) Nov 20, 2018
embed Fix golangci-lint and add Travis integration (#2) Nov 18, 2018
examples Migrate to voice gateway version 4 (#52) Nov 1, 2019
guild Allow the AFK channel to be disabled and add the AFKTimeout type for … Jan 26, 2019
integration Rename project from Discord to Harmony (#7) Nov 20, 2018
internal Properly stop reconnect loop with Disconnect (#63) Nov 8, 2019
invite
log
message Migrate to voice gateway version 4 (#52) Nov 1, 2019
optional Fix nil optional types (#12) Dec 14, 2018
permission Add support for querying guild audit log (#31) Jul 1, 2019
role NewInvite now takes settings like other similar methods (#22) Feb 7, 2019
voice Properly stop reconnect loop with Disconnect (#63) Nov 8, 2019
webhook Rename project from Discord to Harmony (#7) Nov 20, 2018
.gitignore Initial commit Nov 9, 2018
.travis.yml Disable e2e tests on CI, enable `goimports` for golangci-lint Oct 19, 2019
CODE_OF_CONDUCT.md Initial commit Nov 9, 2018
CONTRIBUTING.md Rename project from Discord to Harmony (#7) Nov 20, 2018
LICENSE Initial commit Nov 9, 2018
README.md Update README and some documentation (#48) Oct 22, 2019
activity.go
application_info.go Update channel and message types (#47) Oct 26, 2019
backoff.go Rename project from Discord to Harmony (#7) Nov 20, 2018
channel.go Add the RateLimitPerUser property for Channels (#39) Oct 13, 2019
channel_message.go Update channel and message types (#47) Oct 26, 2019
client.go Properly stop reconnect loop with Disconnect (#63) Nov 8, 2019
client_options.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
clone.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
connection.go Rename project from Discord to Harmony (#7) Nov 20, 2018
dispatch.go Use Uber's atomic package (#60) Nov 3, 2019
error.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
events.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
file.go Improve the way to send files (#25) Feb 8, 2019
gateway.go
gateway_connection.go Properly stop reconnect loop with Disconnect (#63) Nov 8, 2019
go.mod Use Uber's atomic package (#60) Nov 3, 2019
go.sum Use Uber's atomic package (#60) Nov 3, 2019
guild.go
guild_audit_log.go Attach AuditLog to GuildResource (#49) Oct 24, 2019
guild_ban.go Add audit log reason support (#29) Feb 17, 2019
guild_emoji.go Add audit log reason support (#29) Feb 17, 2019
guild_integration.go Update some methods signature for consistency and documentation (#38) Oct 13, 2019
guild_member.go Update some methods signature for consistency and documentation (#38) Oct 13, 2019
guild_permission.go
guild_role.go Add audit log reason support (#29) Feb 17, 2019
handle_event.go Use Uber's atomic package (#60) Nov 3, 2019
harmony.go Prepare release v0.15.0 (#55) Nov 1, 2019
harmony_test.go Update some methods signature for consistency and documentation (#38) Oct 13, 2019
heartbeat.go
identify.go Use Uber's atomic package (#60) Nov 3, 2019
invite.go Add audit log reason support (#29) Feb 17, 2019
listen.go
multipart_upload.go Add audit log reason support (#29) Feb 17, 2019
notes.md Initial commit Nov 9, 2018
opcode.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
payload.go Change websocket library (#50) Oct 27, 2019
ready.go
request.go Update some methods signature for consistency and documentation (#38) Oct 13, 2019
rich_presence.go Rename project from Discord to Harmony (#7) Nov 20, 2018
snowflake.go Rename project from Discord to Harmony (#7) Nov 20, 2018
state.go Fix voice states in client state (#61) Nov 6, 2019
todo.md
user.go Change websocket library (#50) Oct 27, 2019
voice.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
voice_connection.go Use Uber's atomic package (#60) Nov 3, 2019
webhook.go Update some methods signature for consistency and documentation (#38) Oct 13, 2019

README.md

GoDoc License MIT Discord Build Status

Harmony

Harmony is a peaceful Go module for interacting with Discord's API.

Although this package is usable, it still is under active development so please don't use it for anything other than experiments, yet.

Contents

Installation

Make sure you have a working Go installation, if not see this page first.

Then, install this package with the go get command:

go get github.com/skwair/harmony

Note that go get will always pull the latest version from the master branch before Go 1.11. With newer versions and Go modules enabled, the latest minor or patch release will be downloaded. go get github.com/skwair/harmony@major.minor.patch can be used to download a specific version. See Go modules for more information.

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/skwair/harmony"
)

func main() {
    client, err := harmony.NewClient("your.bot.token")
    if err != nil {
        log.Fatal(err)
    }

    // Get information about the current user.
    u, err := client.CurrentUser().Get(context.Background())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(u)
}

For information about how to create bots and more examples on how to use this package, check out the examples directory and the tests.

Testing

For now, only some end to end tests are provided with this module. To run them, you will need a valid bot token and a valid Discord server ID. The bot attached to the token must be in the server with administrator permissions.

  1. Create a Discord test server

From a Discord client and with you main account, simply create a new server. Then, right click on the new server and get it's ID.

Note that for the UI to have the Copy ID option when right clicking on the server, you will need to enable developer mode. You can find this option in User settings > Appearance > Advanced > Developer Mode.

  1. Create a bot and add it to the test Discord server

Create a bot (or use an existing one) and add it to the freshly created server.

See the example directory for information on how to create a bot and add it to a server.

  1. Set required environment variables and run the tests

Set HARMONY_TEST_BOT_TOKEN to the token of your bot and HARMONY_TEST_GUILD_ID to the ID of the server you created and simply run:

⚠️ For the tests to be reproducible, they will start by deleting ALL channels in the provided server. Please make sure to provide a server created ONLY for those tests. ⚠️

go test -v -race ./...

Step 1 and 2 must be done only once for initial setup. Once you have your bot token and the ID of your test server, you can run the tests as many times as you want.

How does it compare to DiscordGo?

Harmony exposes its API differently. It uses a resource-based approach which organizes methods by topic, greatly reducing the number of methods on the main Client type. The goal by doing this is to have a more friendly API which is easier to navigate.

Another key difference is in the "event handler" mechanism. Instead of having a single method that takes an interface{} as a parameter and guesses for which event you registered a handler based on its concrete type, this library provides a dedicated method for each event type, making it clear what signature your handler must have and ensuring it at compile time, not at runtime.

Each action that results in an entry in the audit log has a ...WithReason form, allowing to set a reason for the change (see the X-Audit-Log-Reason header documentation for more information).

Finally, this library has a full support of the context package, allowing the use of timeouts, deadlines and cancellation when interacting with Discord's API.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Original logo by Renee French, dressed with the cool t-shirt by @HlneChd.

You can’t perform that action at this time.