{"id":13410231,"url":"https://github.com/andersfylling/disgord","last_synced_at":"2025-03-14T15:32:08.724Z","repository":{"id":40685898,"uuid":"109882249","full_name":"andersfylling/disgord","owner":"andersfylling","description":"Go module for interacting with the documented Discord's bot interface; Gateway, REST requests and voice","archived":true,"fork":false,"pushed_at":"2024-03-10T09:14:06.000Z","size":22249,"stargazers_count":496,"open_issues_count":44,"forks_count":70,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-09-30T23:48:45.397Z","etag":null,"topics":["api","bindings","bot","discord","discord-api","disgord","go","golang","golang-bindings","golang-module","voice"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andersfylling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"auditlog.go","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["andersfylling"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2017-11-07T19:39:32.000Z","updated_at":"2024-09-10T14:17:26.000Z","dependencies_parsed_at":"2023-02-08T19:46:28.072Z","dependency_job_id":"9b73867a-4c0f-46a8-9796-7dbfdf6bd636","html_url":"https://github.com/andersfylling/disgord","commit_stats":null,"previous_names":["andersfylling/discord"],"tags_count":136,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersfylling%2Fdisgord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersfylling%2Fdisgord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersfylling%2Fdisgord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andersfylling%2Fdisgord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andersfylling","download_url":"https://codeload.github.com/andersfylling/disgord/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243600707,"owners_count":20317321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bindings","bot","discord","discord-api","disgord","go","golang","golang-bindings","golang-module","voice"],"created_at":"2024-07-30T20:01:05.683Z","updated_at":"2025-03-14T15:32:08.244Z","avatar_url":"https://github.com/andersfylling.png","language":"Go","funding_links":["https://github.com/sponsors/andersfylling"],"categories":["API Libraries","Go","Libraries"],"sub_categories":["Go"],"readme":"\u003cdiv align='center'\u003e\n  \u003cimg src=\"/.github/disgord-draft-8.jpeg\" alt='Build Status' /\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://codecov.io/gh/andersfylling/disgord\"\u003e\n      \u003cimg src=\"https://codecov.io/gh/andersfylling/disgord/branch/develop/graph/badge.svg\" /\u003e\n    \u003c/a\u003e\n    \u003ca href='https://goreportcard.com/report/github.com/andersfylling/disgord'\u003e\n      \u003cimg src='https://goreportcard.com/badge/github.com/andersfylling/disgord' alt='Code coverage' /\u003e\n    \u003c/a\u003e\n    \u003ca href='https://pkg.go.dev/github.com/andersfylling/disgord'\u003e\n      \u003cimg src=\"https://pkg.go.dev/badge/andersfylling/disgord\" alt=\"PkgGoDev\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href='https://discord.gg/fQgmBg'\u003e\n      \u003cimg src='https://img.shields.io/badge/Discord%20Gophers-%23disgord-blue.svg' alt='Discord Gophers' /\u003e\n    \u003c/a\u003e\n    \u003ca href='https://discord.gg/HBTHbme'\u003e\n      \u003cimg src='https://img.shields.io/badge/Discord%20API-%23disgord-blue.svg' alt='Discord API' /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n## About\nGo module with context support that handles some of the difficulties from interacting with Discord's bot interface for you; websocket sharding, auto-scaling of websocket connections, advanced caching (cache replacement strategies to restrict memory usage), helper functions, middlewares and lifetime controllers for event handlers, etc.\n\nThis package is intented to be used with the gateway to keep the cache up to date. You should treat data as read only, since they simply represent the discord state. To change the discord state you can use the REST methods and the gateway commands, which will eventually update your local state as well.\n\nIf you want a more lightweight experience you can disable/reject events that you do not need or want to keep track of. Be careful as this might break certain things.\n\n## Tips\n - Use disgord.Snowflake, not snowflake.Snowflake.\n - Use disgord.Time, not time.Time when dealing with Discord timestamps.\n\nYou must explicitly set intents if you want certain gateway events.\n```go\nclient := disgord.New(disgord.Config{\n    Intents: disgord.IntentDirectMessages | disgord.IntentDirectMessageReactions,\n})\n```\n```go\nclient := disgord.New(disgord.Config{\n    Intents: disgord.AllIntents(),\n})\n```\n\n## Starter guide\n\u003e This project uses [Go Modules](https://github.com/golang/go/wiki/Modules) for dealing with dependencies, remember to activate module support in your IDE\n\n\u003e Examples can be found in [examples](examples) and some open source projects Disgord projects in the [wiki](https://pkg.go.dev/github.com/andersfylling/disgord?tab=importedby)\n\nI highly suggest reading the [Discord API documentation](https://discord.com/developers/docs/intro) and the [Disgord go doc](https://pkg.go.dev/github.com/andersfylling/disgord?tab=doc).\n\nSimply use [this github template](https://github.com/andersfylling/disgord-starter) to create your first new bot!\n\n\n## API / Interface\n\n\u003e In short Disgord uses the builder pattern by respecting resources\n\nThe `Client` or `Session` holds are the relevant methods for interacting with Discord. The API is split by resource, such that Guild related information is found in `Client.Guild(guild_id)`, while user related info is found in `Client.User(user_id)`, gateway interaction is found in `Client.Gateway()`, the same for Channel, CurrentUser, Emoji, AuditLog, etc.\n\nCancellation is supported by calling `.WithContext(context.Context` before the final REST call (.Get(), .Update(), etc.).\n\n### Events\n\n\u003e every event goes through the cache layer!\n\nFor Events, Disgord uses the [reactor pattern](https://dzone.com/articles/understanding-reactor-pattern-thread-based-and-eve). This supports both channels and functions. You chose your preference.\n\n### REST\nIf the request is a standard GET request, the cache is always checked first to reduce delay, network traffic and load on the Discord servers. And on responses, regardless of the http method, the data is copied into the cache.\n\n```go\n// bypasses local cache\nclient.CurrentUser().Get(disgord.IgnoreCache)\nclient.Guild(guildID).GetMembers(disgord.IgnoreCache)\n\n// always checks the local cache first\nclient.CurrentUser().Get()\nclient.Guild(guildID).GetMembers()\n\n// with cancellation\ndeadline, _ := context.WithDeadline(context.Background(), time.Now().Add(2*time.Second))\nclient.CurrentUser().WithContext(deadline).Get()\n```\n\n### Voice\nWhenever you want the bot to join a voice channel, a websocket and UDP connection is established. So if your bot is currently in 5 voice channels, then you have 5 websocket connections and 5 udp connections open to handle the voice traffic.\n\n### Cache\nThe cache tries to represent the Discord state as accurate as it can. Because of this, the cache is immutable by default. Meaning the does not allow you to reference any cached objects directly, and every incoming and outgoing data of the cache is deep copied.\n\n## Contributing\n\u003e Please see the [CONTRIBUTING.md file](CONTRIBUTING.md) (Note that it can be useful to read this regardless if you have the time)\n\nYou can contribute with pull requests, issues, wiki updates and helping out in the discord servers mentioned above.\n\nTo notify about bugs or suggesting enhancements, simply create a issue. The more the better. But be detailed enough that it can be reproduced and please provide logs.\n\nTo contribute with code, always create an issue before you open a pull request. This allows automating change logs and releases.\n\nRemember to have stringer installed to run go generate:\n`go get -u golang.org/x/tools/cmd/stringer`\n\n## Sponsors\n\u003e [JetBrains](https://www.jetbrains.com/?from=github.com/andersfylling/disgord)\n\nA Special thanks to the following companies for sponsoring this project!\n\n\n\u003cdiv align='left'\u003e\n  \u003ca href=\"https://www.jetbrains.com/?from=github.com/andersfylling/disgord\"\u003e\n    \u003cimg src=\"/.github/jetbrains-variant-4.svg\" alt=\"JetBrains\" width=\"200px\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n#### Software used\n\n\u003cdiv align='left'\u003e\n  \u003ca href=\"https://www.jetbrains.com/go/?from=github.com/andersfylling/disgord\"\u003e\n    \u003cimg src=\"/.github/icon-goland.svg\" alt=\"GoLand\" width=\"150px\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## Q\u0026A\n\u003e **NOTE:** To see more examples go to the [examples folder](examples). See the GoDoc for a in-depth introduction on the various topics.\n\n```Markdown\n1. How do I find my bot token and/or add my bot to a server?\n\nTutorial here: https://github.com/andersfylling/disgord/wiki/Get-bot-token-and-add-it-to-a-server\n```\n\n```Markdown\n2. Is there an alternative Go package?\n\nYes, it's called DiscordGo (https://github.com/bwmarrin/discordgo). Its purpose is to provide a \nminimalistic API wrapper for Discord, it does not handle multiple websocket sharding, scaling, etc. \nbehind the scenes such as Disgord does. Currently I do not have a comparison chart of Disgord and \nDiscordGo. But I do want to create one in the future, for now the biggest difference is that \nDisgord does not support self bots.\n```\n\n```Markdown\n3. Why make another Discord lib in Go?\n\nI'm trying to take over the world and then become a intergalactic war lord. Have to start somewhere.\n```\n\n```Markdown\n4. Will Disgord support self bots?\n\nNo. Self bots are againts ToS and could result in account termination (see\nhttps://support.discord.com/hc/en-us/articles/115002192352-Automated-user-accounts-self-bots-). \nIn addition, self bots aren't a part of the official Discord API, meaning support could change at\nany time and Disgord could break unexpectedly if this feature were to be added.\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandersfylling%2Fdisgord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandersfylling%2Fdisgord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandersfylling%2Fdisgord/lists"}