@spec add_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Api.options()
) ::
  Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.Member.t()} | {:ok}

Puts a user in a guild.

This endpoint fires the Nostrum.Consumer.guild_member_add/0 event. It requires the CREATE_INSTANT_INVITE permission. Additionally, it situationally requires the MANAGE_NICKNAMES, MANAGE_ROLES, MUTE_MEMBERS, and DEAFEN_MEMBERS permissions.

If successful, returns {:ok, member} or {:ok} if the user was already a member of the guild. Otherwise, returns a Nostrum.Api.error/0.

Options

• :access_token (string) - the user's oauth2 access token
• :nick (string) - value to set users nickname to
• :roles (list of Nostrum.Struct.Guild.Role.id/0) - array of role ids the member is assigned
• :mute (boolean) - if the user is muted
• :deaf (boolean) - if the user is deafened

:access_token is always required.

Examples

Nostrum.Api.Guild.add_member(
  41771983423143937,
  18374719829378473,
  access_token: "6qrZcUqja7812RVdnEKjpzOL4CvHBFG",
  nick: "nostrum",
  roles: [431849301, 913809431]
)

@spec add_member_role(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.Role.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok}

Adds a role to a member.

Role to add is specified by role_id. User to add role to is specified by guild_id and user_id. An optional reason can be given for the audit log.

@spec audit_log(Nostrum.Struct.Guild.id(), Nostrum.Api.options()) ::
  {:ok, Nostrum.Struct.Guild.AuditLog.t()} | Nostrum.Api.error()

Get the Nostrum.Struct.Guild.AuditLog.t/0 for the given guild_id.

Options

• :user_id (Nostrum.Struct.User.id/0) - filter the log for a user ID
• :action_type (integer/0) - filter the log by audit log type, see Audit Log Events
• :before (t:Nostrum.Struct.Snowflake.t/0) - filter the log before a certain entry ID
• :limit (pos_integer/0) - how many entries are returned (default 50, minimum 1, maximum 100)

@spec ban(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
  Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.Ban.t()}

Gets a ban object for the given user from a guild.

@spec ban_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  integer(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok}

Bans a user from a guild.

User to delete is specified by guild_id and user_id. An optional reason can be specified for the audit log.

@spec bans(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.User.t()]}

Gets a list of users banned from a guild.

Guild to get bans for is specified by guild_id.

@spec begin_prune(
  Nostrum.Struct.Guild.id(),
  1..30,
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) ::
  Nostrum.Api.error() | {:ok, %{pruned: integer()}}

Begins a guild prune to prune members within days.

An optional reason can be provided for the guild audit log.

This endpoint requires the KICK_MEMBERS permission. It fires multiple Nostrum.Consumer.guild_member_remove/0 events.

If successful, returns {:ok, %{pruned: pruned}}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.begin_prune(81384788765712384, 1)
{:ok, %{pruned: 0}}

@spec channels(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.Channel.guild_channel()]}

Gets a list of guild channels.

If successful, returns {:ok, channels}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.channels(81384788765712384)
{:ok, [%Nostrum.Struct.Channel{guild_id: 81384788765712384} | _]}

@spec create_emoji(
  Nostrum.Struct.Guild.id(),
  Nostrum.Api.options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok, Nostrum.Struct.Emoji.t()}

Creates a new emoji for the given guild.

This endpoint requires the MANAGE_EMOJIS permission. It fires a Nostrum.Consumer.guild_emojis_update/0 event.

An optional reason can be provided for the audit log.

If successful, returns {:ok, emoji}. Otherwise, returns Nostrum.Api.error/0.

Options

• :name (string) - name of the emoji
• :image (base64 data URI) - the 128x128 emoji image. Maximum size of 256kb
• :roles (list of Nostrum.Snowflake.t/0) - roles for which this emoji will be whitelisted (default: [])

:name and :image are always required.

Examples

image = "data:image/png;base64,YXl5IGJieSB1IGx1a2luIDQgc3VtIGZ1az8="

Nostrum.Api.Guild.create_emoji(43189401384091, name: "nostrum", image: image, roles: [])

@spec create_integration(integer(), %{type: String.t(), id: integer()}) ::
  Nostrum.Api.error() | {:ok}

Creates a new guild integeration.

Guild to create integration with is specified by guild_id.

options is a map with the following requires keys:

• type - Integration type.
• id - Integeration id.

@spec create_role(
  Nostrum.Struct.Guild.id(),
  Nostrum.Api.options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.Role.t()}

Creates a guild role.

An optional reason for the audit log can be provided via reason.

This endpoint requires the MANAGE_ROLES permission. It fires a Nostrum.Consumer.guild_role_create/0 event.

If successful, returns {:ok, role}. Otherwise, returns a Nostrum.Api.error/0.

Options

• :name (string) - name of the role (default: "new role")
• :permissions (integer) - bitwise of the enabled/disabled permissions (default: @everyone perms)
• :color (integer) - RGB color value (default: 0)
• :hoist (boolean) - whether the role should be displayed separately in the sidebar (default: false)
• :mentionable (boolean) - whether the role should be mentionable (default: false)
• :icon (string) - URL role icon (default: nil)
• :unicode_emoji (string) - standard unicode character emoji role icon (default: nil)

Examples

Nostrum.Api.Guild.create_role(41771983423143937, name: "nostrum-club", hoist: true)

@spec delete(Nostrum.Struct.Guild.id()) :: Nostrum.Api.error() | {:ok}

Deletes a guild.

This endpoint requires that the current user is the owner of the guild. It fires the Nostrum.Consumer.guild_delete/0 event.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.delete(81384788765712384)
{:ok}

@spec delete_emoji(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Emoji.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok}

Deletes the given emoji.

An optional reason can be provided for the audit log.

This endpoint requires the MANAGE_EMOJIS permission. It fires a Nostrum.Consumer.guild_emojis_update/0 event.

If successful, returns {:ok}. Otherwise, returns Nostrum.Api.error/0.

@spec delete_integration(Nostrum.Struct.Guild.id(), integer()) ::
  Nostrum.Api.error() | {:ok}

Deletes a guild integeration.

Integration to delete is specified by guild_id and integeration_id.

@spec delete_role(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Role.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok}

Deletes a role from a guild.

An optional reason can be specified for the audit log.

This endpoint requires the MANAGE_ROLES permission. It fires a Nostrum.Consumer.guild_role_delete/0 event.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.delete_role(41771983423143937, 392817238471936)

@spec emoji(Nostrum.Struct.Guild.id(), Nostrum.Struct.Emoji.id()) ::
  Nostrum.Api.error() | {:ok, Nostrum.Struct.Emoji.t()}

Gets an emoji for the given guild and emoji ids.

This endpoint requires the MANAGE_EMOJIS permission.

If successful, returns {:ok, emoji}. Otherwise, returns Nostrum.Api.error/0.

@spec emojis(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.Emoji.t()]}

Gets a list of emojis for a given guild.

This endpoint requires the MANAGE_EMOJIS permission.

If successful, returns {:ok, emojis}. Otherwise, returns Nostrum.Api.error/0.

@spec estimate_prune_count(Nostrum.Struct.Guild.id(), 1..30) ::
  Nostrum.Api.error() | {:ok, %{pruned: integer()}}

Gets the number of members that would be removed in a prune given days.

This endpoint requires the KICK_MEMBERS permission.

If successful, returns {:ok, %{pruned: pruned}}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.estimate_prune_count(81384788765712384, 1)
{:ok, %{pruned: 0}}

@spec get(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.rest_guild()}

Gets a guild.

If successful, returns {:ok, guild}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.get(81384788765712384)
{:ok, %Nostrum.Struct.Guild{id: 81384788765712384}}

@spec integrations(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.Guild.Integration.t()]}

Gets a list of guild integerations.

Guild to get integrations for is specified by guild_id.

@spec kick_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok}

Removes a member from a guild.

This event requires the KICK_MEMBERS permission. It fires a Nostrum.Consumer.guild_member_remove/0 event.

An optional reason can be provided for the audit log with reason.

If successful, returns {:ok}. Otherwise, returns a Nostrum.Api.error/0.

Examples

iex> Nostrum.Api.Guild.kick_member(1453827904102291, 18739485766253)
{:ok}

@spec leave(Nostrum.Struct.Guild.id()) :: Nostrum.Api.error() | {:ok}

Leaves a guild.

Guild to leave is specified by guild_id.

@spec member(Nostrum.Struct.Guild.id(), Nostrum.Struct.User.id()) ::
  Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.Member.t()}

Gets a guild member.

If successful, returns {:ok, member}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.member(4019283754613, 184937267485)

@spec members(Nostrum.Struct.Guild.id(), Nostrum.Api.options()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.Guild.Member.t()]}

Gets a list of a guild's members.

If successful, returns {:ok, members}. Otherwise, returns a Nostrum.Api.error/0.

Options

• :limit (integer) - max number of members to return (1-1000) (default: 1)
• :after (Nostrum.Struct.User.id/0) - the highest user id in the previous page (default: 0)

Examples

Nostrum.Api.Guild.members(41771983423143937, limit: 1)

@spec modify(
  Nostrum.Struct.Guild.id(),
  Nostrum.Api.options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.rest_guild()}

Modifies a guild's settings.

This endpoint requires the MANAGE_GUILD permission. It fires the Nostrum.Consumer.guild_update/0 event.

An optional reason can be provided for the audit log.

If successful, returns {:ok, guild}. Otherwise, returns a Nostrum.Api.error/0.

Options

• :name (string) - guild name
• :region (string) - guild voice region id
• :verification_level (integer) - verification level
• :default_message_notifications (integer) - default message notification level
• :explicit_content_filter (integer) - explicit content filter level
• :afk_channel_id (Nostrum.Snowflake.t/0) - id for afk channel
• :afk_timeout (integer) - afk timeout in seconds
• :icon (base64 data URI) - 128x128 jpeg image for the guild icon
• :owner_id (Nostrum.Snowflake.t/0) - user id to transfer guild ownership to (must be owner)
• :splash (base64 data URI) - 128x128 jpeg image for the guild splash (VIP only)
• :system_channel_id (Nostrum.Snowflake.t/0) - the id of the channel to which system messages are sent
• :rules_channel_id (Nostrum.Snowflake.t/0) - the id of the channel that is used for rules in public guilds
• :public_updates_channel_id (Nostrum.Snowflake.t/0) - the id of the channel where admins and moderators receive notices from Discord in public guilds

Examples

Nostrum.Api.Guild.modify(451824027976073216, name: "Nose Drum")
{:ok, %Nostrum.Struct.Guild{id: 451824027976073216, name: "Nose Drum", ...}}

@spec modify_channel_positions(Nostrum.Struct.Guild.id(), [
  %{id: Nostrum.Struct.Channel.id(), position: integer()}
]) :: Nostrum.Api.error() | {:ok}

Reorders a guild's channels.

This endpoint requires the MANAGE_CHANNELS permission. It fires multiple Nostrum.Consumer.channel_update/0 events.

If successful, returns {:ok, channels}. Otherwise, returns a Nostrum.Api.error/0.

positions is a list of maps that each map a channel id with a position.

Examples

Nostrum.Api.Guild.modify_channel_positions(279093381723062272, [%{id: 351500354581692420, position: 2}])
{:ok}

@spec modify_emoji(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Emoji.id(),
  Nostrum.Api.options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok, Nostrum.Struct.Emoji.t()}

Modify the given emoji.

This endpoint requires the MANAGE_EMOJIS permission. It fires a Nostrum.Consumer.guild_emojis_update/0 event.

An optional reason can be provided for the audit log.

If successful, returns {:ok, emoji}. Otherwise, returns Nostrum.Api.error/0.

Options

• :name (string) - name of the emoji
• :roles (list of Nostrum.Snowflake.t/0) - roles to which this emoji will be whitelisted

Examples

Nostrum.Api.Guild.modify_emoji(43189401384091, 4314301984301, name: "elixir", roles: [])

@spec modify_integration(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Integration.id(),
  %{
    expire_behaviour: integer(),
    expire_grace_period: integer(),
    enable_emoticons: boolean()
  }
) :: Nostrum.Api.error() | {:ok}

Changes the settings and behaviours for a guild integeration.

Integration to modify is specified by guild_id and integeration_id.

options is a map with the following keys:

• expire_behavior - Expiry behavior.
• expire_grace_period - Period where the integration will ignore elapsed subs.
• enable_emoticons - Whether emoticons should be synced.

@spec modify_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Api.options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.Member.t()}

Modifies a guild member's attributes.

This endpoint fires the Nostrum.Consumer.guild_member_update/0 event. It situationally requires the MANAGE_NICKNAMES, MANAGE_ROLES, MUTE_MEMBERS, DEAFEN_MEMBERS, and MOVE_MEMBERS permissions.

If successful, returns {:ok, member}. Otherwise, returns a Nostrum.Api.error/0.

An optional reason argument can be given for the audit log.

Options

• :nick (string) - value to set users nickname to
• :roles (list of Nostrum.Snowflake.t/0) - array of role ids the member is assigned
• :mute (boolean) - if the user is muted
• :deaf (boolean) - if the user is deafened
• :channel_id (Nostrum.Snowflake.t/0) - id of channel to move user to (if they are connected to voice)
• :communication_disabled_until (DateTime.t/0 or nil) - datetime to disable user communication (timeout) until, or nil to remove timeout.

Examples

Nostrum.Api.Guild.modify_member(41771983423143937, 637162356451, nick: "Nostrum")
{:ok, %Nostrum.Struct.Member{}}

@spec modify_role(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Role.id(),
  Nostrum.Api.options(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok, Nostrum.Struct.Guild.Role.t()}

Modifies a guild role.

This endpoint requires the MANAGE_ROLES permission. It fires a Nostrum.Consumer.guild_role_update/0 event.

An optional reason can be specified for the audit log.

If successful, returns {:ok, role}. Otherwise, returns a Nostrum.Api.error/0.

Options

• :name (string) - name of the role
• :permissions (integer) - bitwise of the enabled/disabled permissions
• :color (integer) - RGB color value (default: 0)
• :hoist (boolean) - whether the role should be displayed separately in the sidebar
• :mentionable (boolean) - whether the role should be mentionable

Examples

Nostrum.Api.Guild.modify_role(41771983423143937, 392817238471936, hoist: false, name: "foo-bar")

@spec modify_role_positions(
  Nostrum.Struct.Guild.id(),
  [%{id: Nostrum.Struct.Guild.Role.id(), position: integer()}],
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}

Reorders a guild's roles.

This endpoint requires the MANAGE_ROLES permission. It fires multiple Nostrum.Consumer.guild_role_update/0 events.

If successful, returns {:ok, roles}. Otherwise, returns a Nostrum.Api.error/0.

positions is a list of maps that each map a role id with a position.

Examples

Nostrum.Api.Guild.modify_role_positions(41771983423143937, [%{id: 41771983423143936, position: 2}])

@spec modify_self_nick(Nostrum.Struct.Guild.id(), Nostrum.Api.options()) ::
  Nostrum.Api.error() | {:ok, %{nick: String.t()}}

Modifies the nickname of the current user in a guild.

If successful, returns {:ok, %{nick: nick}}. Otherwise, returns a Nostrum.Api.error/0.

Options

• :nick (string) - value to set users nickname to

Examples

Nostrum.Api.Guild.modify_self_nick(41771983423143937, nick: "Nostrum")
{:ok, %{nick: "Nostrum"}}

@spec modify_widget(Nostrum.Struct.Guild.id(), map()) ::
  Nostrum.Api.error() | {:ok, map()}

Modifies a guild embed.

@spec remove_member_role(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.Role.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok}

Removes a role from a member.

Role to remove is specified by role_id. User to remove role from is specified by guild_id and user_id. An optional reason can be given for the audit log.

@spec roles(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.Guild.Role.t()]}

Gets a guild's roles.

If successful, returns {:ok, roles}. Otherwise, returns a Nostrum.Api.error/0.

Examples

Nostrum.Api.Guild.roles(147362948571673)

@spec scheduled_events(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.Guild.ScheduledEvent.t()]}

Get a list of scheduled events for a guild.

@spec sync_integration(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.Guild.Integration.id()
) ::
  Nostrum.Api.error() | {:ok}

Syncs a guild integration.

Integration to sync is specified by guild_id and integeration_id.

@spec unban_member(
  Nostrum.Struct.Guild.id(),
  Nostrum.Struct.User.id(),
  Nostrum.Struct.Guild.AuditLogEntry.reason()
) :: Nostrum.Api.error() | {:ok}

Removes a ban for a user.

User to unban is specified by guild_id and user_id. An optional reason can be specified for the audit log.

@spec voice_region(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.VoiceRegion.t()]}

Gets a list of voice regions for the guild.

Guild to get voice regions for is specified by guild_id.

@spec voice_regions() :: Nostrum.Api.error() | {:ok, [Nostrum.Struct.VoiceRegion.t()]}

Gets a list of voice regions.

@spec webhooks(Nostrum.Struct.Guild.id()) ::
  Nostrum.Api.error() | {:ok, [Nostrum.Struct.Webhook.t()]}

Gets a list of webhooks for a guild.

Parameters

• guild_id - Guild to get webhooks for.

@spec widget(Nostrum.Struct.Guild.id()) :: Nostrum.Api.error() | {:ok, map()}

Gets a guild embed.