Skip to content
Harmony is a peaceful Go module for interacting with Discord's API
Go
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
_scripts
audit
channel Update channel and message types (#47) Oct 26, 2019
debug
embed Fix golangci-lint and add Travis integration (#2) Nov 18, 2018
examples Migrate to voice gateway version 4 (#52) Nov 1, 2019
guild
integration
internal
invite
log Migrate to voice gateway version 4 (#52) Nov 1, 2019
message
optional
permission
role NewInvite now takes settings like other similar methods (#22) Feb 7, 2019
voice
webhook
.gitignore Initial commit Nov 9, 2018
.travis.yml
CODE_OF_CONDUCT.md Initial commit Nov 9, 2018
CONTRIBUTING.md
LICENSE
README.md
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
channel_message.go Update channel and message types (#47) Oct 26, 2019
client.go
client_options.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
clone.go
connection.go
dispatch.go
error.go
events.go
file.go Improve the way to send files (#25) Feb 8, 2019
gateway.go
gateway_connection.go
go.mod Use Uber's atomic package (#60) Nov 3, 2019
go.sum
guild.go
guild_audit_log.go
guild_ban.go
guild_emoji.go
guild_integration.go
guild_member.go Update some methods signature for consistency and documentation (#38) Oct 13, 2019
guild_permission.go Rename project from Discord to Harmony (#7) Nov 20, 2018
guild_role.go Add audit log reason support (#29) Feb 17, 2019
handle_event.go
harmony.go
harmony_test.go
heartbeat.go
identify.go
invite.go
listen.go
multipart_upload.go
notes.md
opcode.go
payload.go
ready.go
request.go
rich_presence.go
snowflake.go
state.go
todo.md
user.go
voice.go Create a new voice package to support external voice connections (#44) Oct 18, 2019
voice_connection.go
webhook.go

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.