api

Documentation

Index

• Variables
• type ChannelAPI
• type DiscordAPI
• type GuildAPI
• type MessageAPI

Variables

var (
	ErrNilEmoji = errors.New("passed a nil Emoji to an API request requiring" +
		" an emoji value")
)

Types

type ChannelAPI

type ChannelAPI interface {
	// Get a channel by ID.
	//
	// Returns a channel object.
	Get(id Snowflake) (Channel, error)

	// Patch updates a channel's settings.
	//
	// Requires the MANAGE_CHANNELS permission for the guild.
	//
	// Fires a Channel Update Gateway event. If modifying a category, individual
	// Channel Update events will fire for each child channel that also changes.
	//
	// Returns a channel on success, and a 400 BAD REQUEST on invalid parameters.
	Patch(Snowflake, dio.ChannelPatch) (Channel, error)

	// Delete a channel, or close a private message.
	//
	// Requires the MANAGE_CHANNELS permission for the guild.
	//
	// Deleting a category does not delete its child channels; they will have
	// their parent_id removed and a Channel Update Gateway event will fire for
	// each of them.
	//
	// Fires a Channel Delete Gateway event.
	//
	// Deleting a guild channel cannot be undone. Use this with caution, as it is
	// impossible to undo this action when performed on a guild channel. In
	// contrast, when used with a private message, it is possible to undo the
	// action by opening a private message with the recipient again.
	//
	// For Community guilds, the Rules or Guidelines channel and the Community
	// Updates channel cannot be deleted.
	Delete(id Snowflake) error

	// EditPermissions updates the channel permission overwrites for a user or
	// role in a channel.
	//
	// Only usable for guild channels.
	//
	// Requires the MANAGE_ROLES permission.
	EditPermissions(id Snowflake, patch dio.ChannelPermissionPatch) error

	// GetInvites returns a list of invite objects (with invite metadata) for the
	// channel.
	//
	// Only usable for guild channels.
	//
	// Requires the MANAGE_CHANNELS permission.
	GetInvites(id Snowflake) ([]Invite, error)

	// DeletePermission deletes a channel permission overwrite for a user or role
	// in a channel.
	//
	// Only usable for guild channels.
	//
	// Requires the MANAGE_ROLES permission.
	DeletePermission(chanId, permId Snowflake) error

	// FollowNewsChannel follows a News Channel to send messages to a target
	// channel.
	//
	// Requires the MANAGE_WEBHOOKS permission in the target channel.
	FollowNewsChannel(chanId, webhookChanId Snowflake) (FollowedChannel, error)

	// TriggerTypingIndicator starts a typing indicator for the specified channel.
	//
	// Generally bots should not implement this route. However, if a bot is
	// responding to a command and expects the computation to take a few seconds,
	// this endpoint may be called to let the user know that the bot is processing
	// their message.
	//
	// Fires a Typing Start Gateway event.
	TriggerTypingIndicator(chanId Snowflake) error

	// GetPinnedMessages returns all pinned messages in the channel as an array of
	// message objects.
	GetPinnedMessages(chanId Snowflake) ([]Message, error)

	// PinChannelMessage pins a message in a channel.
	//
	// Requires the MANAGE_MESSAGES permission.
	//
	// The max pinned messages is 50.
	PinMessage(chanId, msgId Snowflake) error

	// UnpinMessage deletes a pinned message in a channel.
	//
	// Requires the MANAGE_MESSAGES permission.
	UnpinMessage(chanId, msgId Snowflake) error

	// AddGroupRecipient adds a recipient to a Group DM using their access token.
	//
	// TODO: does this return anything? API docs unclear.
	AddGroupRecipient(request dio.AddRecipientRequest) error

	// RemoveGroupRecipient removes a recipient from a group DM.
	RemoveGroupRecipient(chanId, userId Snowflake) error

	Messages() MessageAPI
}

type DiscordAPI

type DiscordAPI interface {
	Guilds() GuildAPI

	Channels() ChannelAPI

	// GetVoiceRegions fetches and returns an array of voice region objects that
	// can be used when creating servers.
	GetVoiceRegions() ([]discord.VoiceRegion, error)
}

type GuildAPI

type GuildAPI interface {
	// CreateGuild creates a new guild.
	//
	// Returns a guild object on success.
	//
	// Fires a Guild Create Gateway event.
	CreateGuild(dio.CreateGuildRequest) (Guild, error)

	// GetGuild fetches and returns the guild object for the given id.
	//
	// If `with_counts` is set to true, this endpoint will also return
	// `approximate_member_count` and `approximate_presence_count` for the guild.
	GetGuild(id Snowflake) (Guild, error)

	// GetGuildPreview fetches and returns the guild preview object for the given
	// id.
	//
	// If the user is not in the guild, then the guild must be Discoverable.
	GetGuildPreview(id Snowflake) (GuildPreview, error)

	// GetAuditLogs returns an audit log object for the guild.
	//
	// Requires the 'VIEW_AUDIT_LOG' permission.
	GetAuditLogs(id Snowflake) (audit.Log, error)
}

type MessageAPI

type MessageAPI interface {
	// GetMessages returns the messages for a channel.
	//
	// If operating on a guild channel, this endpoint requires the VIEW_CHANNEL
	// permission to be present on the current user. If the current user is
	// missing the 'READ_MESSAGE_HISTORY' permission in the channel then this will
	// return no messages (since they cannot read the message history).
	//
	// Passing a nil value to this method will result in no filters being applied.
	//
	// Returns an array of message objects on success.
	GetMessages(dio.MessageFilter) ([]discord.Message, error)

	// GetMessage Returns a specific message in the channel. If operating on a
	// guild channel, this endpoint requires the 'READ_MESSAGE_HISTORY' permission
	// to be present on the current user.
	//
	// Returns a message object on success.
	GetMessage(id discord.Snowflake) (discord.Message, error)

	// PostJSONMessage creates a new message for a guild text or DM channel.
	//
	// Before using this endpoint, you must connect to and identify with a gateway
	// at least once.
	//
	// Discord may strip certain characters from message content, like invalid
	// unicode characters or characters which cause unexpected message formatting.
	//
	// If you are passing user-generated strings into message content, consider
	// sanitizing the data to prevent unexpected behavior and utilizing
	// `allowed_mentions` to prevent unexpected mentions.
	//
	// If operating on a guild channel, this endpoint requires the SEND_MESSAGES
	// permission to be present on the current user. If the `tts` field is set to
	// true, the SEND_TTS_MESSAGES permission is required for the message to be
	// spoken.
	//
	// Fires a Message Create Gateway event. See
	// https://discord.com/developers/docs/reference#message-formatting for more
	// information on how to properly format messages.
	//
	// The maximum request size when sending a message is 8MB.
	//
	// Note that when sending application/json you must send at least one of the
	// fields `content` or `embed`.
	//
	// Returns a message object.
	PostJSONMessage(post dio.JSONMessagePost) (discord.Message, error)

	// PostMultipartMessage creates a new message for a guild text or DM channel.
	//
	// Before using this endpoint, you must connect to and identify with a gateway
	// at least once.
	//
	// Discord may strip certain characters from message content, like invalid
	// unicode characters or characters which cause unexpected message formatting.
	//
	// If you are passing user-generated strings into message content, consider
	// sanitizing the data to prevent unexpected behavior and utilizing
	// `allowed_mentions` to prevent unexpected mentions.
	//
	// If operating on a guild channel, this endpoint requires the SEND_MESSAGES
	// permission to be present on the current user. If the `tts` field is set to
	// true, the SEND_TTS_MESSAGES permission is required for the message to be
	// spoken.
	//
	// Fires a Message Create Gateway event. See
	// https://discord.com/developers/docs/reference#message-formatting for more
	// information on how to properly format messages.
	//
	// The maximum request size when sending a message is 8MB.
	//
	// Note that when sending multipart/form-data, you must send at least one of
	// the fields `content`, `embed` or `file`.
	//
	// Returns a message object.
	PostMultipartMessage(post dio.MultipartMessagePost) (discord.Message, error)

	// CrosspostMessage crossposts the given message in a News Channel to all
	// subscriber channels.
	//
	// This endpoint requires the 'SEND_MESSAGES' permission, if the current user
	// sent the message, or additionally the 'MANAGE_MESSAGES' permission, for all
	// other messages, to be present for the current user.
	//
	// Returns a message object.
	CrosspostMessage(id discord.Snowflake) (discord.Message, error)

	// CreateReaction adds a reaction to the message with the given ID.
	//
	// This endpoint requires the 'READ_MESSAGE_HISTORY' permission to be present
	// on the current user. Additionally, if nobody else has reacted to the
	// message using this emoji, this endpoint requires the 'ADD_REACTIONS'
	// permission to be present on the current user.
	CreateReaction(msgId discord.Snowflake, emoji discord.Emoji) error

	// DeleteOwnReaction delete a reaction the current user has made for the
	// message.
	DeleteOwnReaction(msgId discord.Snowflake, emoji discord.Emoji) error

	// DeleteUserReaction deletes another user's reaction.
	//
	// This endpoint requires the 'MANAGE_MESSAGES' permission to be present on
	// the current user.
	DeleteUserReaction(msgId, userId discord.Snowflake, emoji discord.Emoji) error

	// GetReactions returns a list of users that reacted with this emoji.
	GetReactions(query dio.GetReactionsQuery) ([]discord.User, error)

	// DeleteAllReactions deletes all reactions on a message.
	//
	// This endpoint requires the 'MANAGE_MESSAGES' permission to be present on
	// the current user.
	//
	// Fires a Message MessageReaction Remove All Gateway event.
	DeleteAllReactions(id discord.Snowflake) error

	// DeleteAllReactionsFor deletes all the reactions for the given emoji on a
	// message.
	//
	// This endpoint requires the MANAGE_MESSAGES permission to be present on the
	// current user. Fires a Message MessageReaction Remove Emoji Gateway event.
	DeleteAllReactionsFor(msgId discord.Snowflake, emoji discord.Emoji) error

	// EditMessage patches a previously sent message.
	//
	// The fields `content`, `embed`, `allowed_mentions` and flags can be edited
	// by the original message author. Other users can only edit flags and only if
	// they have the MANAGE_MESSAGES permission in the corresponding channel.
	//
	// When specifying flags, ensure to include all previously set flags/bits in
	// addition to ones that you are modifying. Only flags documented in the table
	// below may be modified by users (unsupported flag changes are currently
	// ignored without error).
	//
	// Fires a Message Update Gateway event.
	//
	// Returns a message object.
	EditMessage(id discord.Snowflake, patch dio.MessagePatch) (discord.Message, error)

	// DeleteMessage deletes an existing message.
	//
	// If operating on a guild channel and trying to delete a message that was not
	// sent by the current user, this endpoint requires the MANAGE_MESSAGES
	// permission.
	//
	// Fires a Message Delete Gateway event.
	DeleteMessage(id discord.Snowflake) error

	// BulkDeleteMessage deletes multiple messages in a single request.
	//
	// This endpoint can only be used on guild channels and requires the
	// MANAGE_MESSAGES permission.
	//
	// Fires a Message Delete Bulk Gateway event.
	//
	// Any message IDs given that do not exist or are invalid will count towards
	// the minimum and maximum message count (currently 2 and 100 respectively).
	//
	// This endpoint will not delete messages older than 2 weeks, and will fail
	// with a 400 BAD REQUEST if any message provided is older than that or if any
	// duplicate message IDs are provided.
	BulkDeleteMessages([]discord.Snowflake) error
}