Nostrum v0.6.0

View Source Nostrum.Struct.Channel (Nostrum v0.6.0)

Struct and helper functions for working with channels.

Channel Struct

The channel struct is used by Nostrum to represent a Discord Channel Object. More information can be found on the Discord API Channel Documentation.

The struct can have one of several forms depending on the type of channel. You can read more about the individual channel types below.

A typical channel would appear as:

%Nostrum.Struct.Channel{
  guild_id: 766435015768539156,
  id: 827333533688397865,
  name: "announcements",
  nsfw: false,
  permission_overwrites: [],
  position: 1,
  type: 5,
}

The channel struct implements String.Chars protocol through the mention/1 function. This example uses our channel from the previous code block.

channel |> to_string()
"<#766435015768539156>"

Channel Cache

The ChannelCache module provides functionality for you to retrieve information about any channel that your application can see. It provides two functions: get/1 and get!/1.

Example 

Nostrum.Cache.ChannelCache.get!(827333533688397865)
%Nostrum.Struct.Channel{
  application_id: nil,
  bitrate: nil,
  guild_id: 766435015768539156,
  icon: nil,
  id: 827333533688397865,
  last_message_id: nil,
  last_pin_timestamp: nil,
  name: "announcements",
  nsfw: false,
  owner_id: nil,
  parent_id: nil,
  permission_overwrites: [
    %Nostrum.Struct.Overwrite{
      allow: 0,
      deny: 2048,
      id: 766435015768539156,
      type: :role
    }
  ],
  position: 1,
  recipients: nil,
  topic: nil,
  type: 5,
  user_limit: nil
}

More details of the cache can be found at Nostrum.Cache.ChannelCache.

Helper Functions

This module contains two functions for assisting with channel structs. mention/1 to convert the channel into a mention as a string, and link/1 to convert the channel into a hyperlink as a string. Further details and examples are detailed in the Functions section of this module.

Api Functions

The Nostrum Api contains numerous functions related to channels. Notable functions relating to channels are shown below.

Note: This is not an exhaustive list, for full details please see the Nostrum.Api module documentation.

Channel Types

Channels take the shape of various types depending on their use and not all fields are always used. The currently implemented channel types are detailed below. The type of channel is determined by the :type field.

This diagram represents the regular channel types 0, 2, 5 and 13.

Discord Channels

The currently implemented channel types are:

Channel Type
0GUILD_TEXTA text channel within a server
1DMA direct message between users
2GUILD_VOICEA voice channel within a server
3GROUP_DMA direct message between multiple users
4GUILD_CATEGORYA category that contains up to 50 channels
5GUILD_NEWSA channel that users can follow and crosspost
6GUILD_STOREA channel to sell games on Discord
10GUILD_NEWS_THREADA temporary sub-channel within a news channel
11GUILD_PUBLIC_THREADA temporary sub-channel within a text channel
12GUILD_PRIVATE_THREADA temporary private sub-channel within a text channel
13GUILD_STAGE_VOICEA voice channel for hosting events with an audience

More information about Discord Channel Types can be found on the Discord API Channel Type Documentation.

Link to this section Summary

Types

application_id()

The id of the application that created a group direct message or thread.

archive_timestamp()

When the thread was archived.

archived()

The threads archived status.

auto_archive_duration()

Archive duration for the thread in minutes.

bitrate()

The bitate of the voice channel.

channel_mention()

A partial channel object representing a channel mention.

default_auto_archive_duration()

Default duration for newly created threads in minutes.

dm_channel()

Type 1 partial channel object representing a direct message.

flags()

User thread settings, currently only used for notifications.

group_dm_channel()

Type 3 partial channel object representing a group direct message.

guild_category_channel()

Type 4 partial channel object representing a channel category.

guild_channel() deprecated

Guild channel types

guild_id()

The id of the guild the channel is located in.

guild_news_channel()

Type 5 partial channel object representing a news channel.

guild_news_thread_channel()

Type 10 partial channel object representing a news thread.

guild_private_thread_channel()

Type 12 partial channel object representing a private thread.

guild_public_thread_channel()

Type 11 partial channel object representing a standard thread.

guild_stage_voice_channel()

Type 13 channel object representing a stage channel.

guild_store_channel()

Type 6 partial channel object representing a store channel.

guild_text_channel()

Type 0 partial channel object representing a text channel within a guild.

guild_voice_channel()

Type 2 partial channel object representing an audio channel within a guild.

icon()

The hash of the channels icon.

id()

The id of the channel object.

join_timestamp()

When the user joined the thread.

last_message_id()

The id of the last message sent in the channel.

last_pin_timestamp()

Timestamp for the last pinned message.

locked()

The threads locked status.

member()

Present when the bot joins a thread.

member_count()

Approximate count of members in a thread, capped at 50.

message_count()

Approximate count of messages in a thread, capped at 50.

name()

The name of the channel.

newly_created()

Included only in the THREAD_CREATE event.

nsfw()

Whether the NSFW setting is enabled for this channel.

owner_id()

The id of the user of a group direct message or thread.

parent_id()

The id of the parent channel that this channel is located under.

permission_overwrites()

A list of permission overwrites applied to the channel.

permissions()

Computed permissions of the invoking user.

position()

The position of the channel in the sidebar of the guild.

rate_limit_per_user()

The users rate limit.

recipients()

A list of users in a group DM.

rtc_region()

Region id for the channel.

t()

All valid channel types.

text_channel() deprecated

All valid text channels.

thread_metadata()

The video quality mode of the voice channel.

topic()

The topic of the channel.

type()

The type of channel.

user_id()

User id of the threads creator.

user_limit()

The user limit of a voice channel.

video_quality_mode()

The video quality mode of the channel.

voice_channel() deprecated

A Nostrum.Struct.Channel that represents a voice channel

Functions

mention(channel)

Convert a channel into a mention.

Link to this section Types

Link to this type

application_id()

View Source

Specs

application_id() :: Nostrum.Snowflake.t() | nil

The id of the application that created a group direct message or thread.

This applies to bot created channels.

Link to this type

archive_timestamp()

View Source (since 0.5.0)

Specs

archive_timestamp() :: DateTime.t() | nil

When the thread was archived.

Link to this type

archived()

View Source (since 0.5.0)

Specs

archived() :: boolean()

The threads archived status.

Link to this type

auto_archive_duration()

View Source (since 0.5.0)

Specs

auto_archive_duration() :: integer()

Archive duration for the thread in minutes.

  • 60, 1 hour
  • 1440, 24 hours
  • 4320, 3 days
  • 10080, 7 days
Link to this type

bitrate()

View Source

Specs

bitrate() :: integer()

The bitate of the voice channel.

Link to this type

channel_mention()

View Source

Specs

channel_mention() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: term(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: name(),
  newly_created: term(),
  nsfw: term(),
  owner_id: term(),
  parent_id: term(),
  permission_overwrites: term(),
  permissions: term(),
  position: term(),
  rate_limit_per_user: term(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: term(),
  topic: term(),
  type: type(),
  user_limit: term(),
  video_quality_mode: term()
}

A partial channel object representing a channel mention.

More information about the Discord Channel Mention Object can be found at the Discord API Channel Mention Object Documentation.

Link to this type

default_auto_archive_duration()

View Source (since 0.5.0)

Specs

default_auto_archive_duration() :: integer()

Default duration for newly created threads in minutes.

  • 60, 1 hour
  • 1440, 24 hours
  • 4320, 3 days
  • 10080, 7 days
Link to this type

dm_channel()

View Source

Specs

dm_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: term(),
  icon: term(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: last_pin_timestamp(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: term(),
  newly_created: term(),
  nsfw: term(),
  owner_id: term(),
  parent_id: term(),
  permission_overwrites: term(),
  permissions: term(),
  position: term(),
  rate_limit_per_user: term(),
  recipients: recipients(),
  rtc_region: term(),
  thread_metadata: term(),
  topic: term(),
  type: 1,
  user_limit: term(),
  video_quality_mode: term()
}

Type 1 partial channel object representing a direct message.

Link to this type

flags()

View Source (since 0.5.0)

Specs

flags() :: integer()

User thread settings, currently only used for notifications.

Link to this type

group_dm_channel()

View Source

Specs

group_dm_channel() :: %Nostrum.Struct.Channel{
  application_id: application_id(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: term(),
  icon: icon(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: name(),
  newly_created: term(),
  nsfw: term(),
  owner_id: owner_id(),
  parent_id: term(),
  permission_overwrites: term(),
  permissions: term(),
  position: term(),
  rate_limit_per_user: term(),
  recipients: recipients(),
  rtc_region: term(),
  thread_metadata: term(),
  topic: term(),
  type: 3,
  user_limit: term(),
  video_quality_mode: term()
}

Type 3 partial channel object representing a group direct message.

Link to this type

guild_category_channel()

View Source

Specs

guild_category_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: term(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: name(),
  newly_created: term(),
  nsfw: nsfw(),
  owner_id: term(),
  parent_id: parent_id(),
  permission_overwrites: permission_overwrites(),
  permissions: term(),
  position: position(),
  rate_limit_per_user: term(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: term(),
  topic: term(),
  type: 4,
  user_limit: term(),
  video_quality_mode: term()
}

Type 4 partial channel object representing a channel category.

Note: Other channels parent_id field refers to this type of object.

Link to this type

guild_channel()

View Source
This type is deprecated. See t.0.

Specs

guild_channel() ::
  guild_text_channel() | guild_voice_channel() | guild_category_channel()

Guild channel types

Link to this type

guild_id()

View Source

Specs

guild_id() :: Nostrum.Struct.Guild.id()

The id of the guild the channel is located in.

Link to this type

guild_news_channel()

View Source (since 0.5.0)

Specs

guild_news_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: default_auto_archive_duration(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: name(),
  newly_created: term(),
  nsfw: nsfw(),
  owner_id: term(),
  parent_id: parent_id(),
  permission_overwrites: permission_overwrites(),
  permissions: term(),
  position: position(),
  rate_limit_per_user: term(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: term(),
  topic: topic(),
  type: 5,
  user_limit: term(),
  video_quality_mode: term()
}

Type 5 partial channel object representing a news channel.

Link to this type

guild_news_thread_channel()

View Source (since 0.5.0)

Specs

guild_news_thread_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: member_count(),
  message_count: message_count(),
  name: name(),
  newly_created: newly_created(),
  nsfw: term(),
  owner_id: owner_id(),
  parent_id: parent_id(),
  permission_overwrites: term(),
  permissions: term(),
  position: term(),
  rate_limit_per_user: rate_limit_per_user(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: thread_metadata(),
  topic: term(),
  type: type(),
  user_limit: term(),
  video_quality_mode: term()
}

Type 10 partial channel object representing a news thread.

Link to this type

guild_private_thread_channel()

View Source (since 0.5.0)

Specs

guild_private_thread_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: member_count(),
  message_count: message_count(),
  name: name(),
  newly_created: newly_created(),
  nsfw: term(),
  owner_id: owner_id(),
  parent_id: parent_id(),
  permission_overwrites: term(),
  permissions: term(),
  position: term(),
  rate_limit_per_user: rate_limit_per_user(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: thread_metadata(),
  topic: term(),
  type: type(),
  user_limit: term(),
  video_quality_mode: term()
}

Type 12 partial channel object representing a private thread.

Link to this type

guild_public_thread_channel()

View Source (since 0.5.0)

Specs

guild_public_thread_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: member_count(),
  message_count: message_count(),
  name: name(),
  newly_created: newly_created(),
  nsfw: term(),
  owner_id: owner_id(),
  parent_id: parent_id(),
  permission_overwrites: term(),
  permissions: term(),
  position: term(),
  rate_limit_per_user: rate_limit_per_user(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: thread_metadata(),
  topic: term(),
  type: type(),
  user_limit: term(),
  video_quality_mode: term()
}

Type 11 partial channel object representing a standard thread.

Link to this type

guild_stage_voice_channel()

View Source (since 0.5.0)

Specs

guild_stage_voice_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: member_count(),
  message_count: message_count(),
  name: name(),
  newly_created: term(),
  nsfw: term(),
  owner_id: owner_id(),
  parent_id: parent_id(),
  permission_overwrites: term(),
  permissions: term(),
  position: term(),
  rate_limit_per_user: rate_limit_per_user(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: thread_metadata(),
  topic: term(),
  type: type(),
  user_limit: term(),
  video_quality_mode: term()
}

Type 13 channel object representing a stage channel.

Link to this type

guild_store_channel()

View Source (since 0.5.0)

Specs

guild_store_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: term(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: name(),
  newly_created: term(),
  nsfw: nsfw(),
  owner_id: term(),
  parent_id: parent_id(),
  permission_overwrites: permission_overwrites(),
  permissions: term(),
  position: position(),
  rate_limit_per_user: term(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: term(),
  topic: term(),
  type: type(),
  user_limit: term(),
  video_quality_mode: term()
}

Type 6 partial channel object representing a store channel.

Link to this type

guild_text_channel()

View Source

Specs

guild_text_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: term(),
  default_auto_archive_duration: default_auto_archive_duration(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: last_message_id(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: name(),
  newly_created: term(),
  nsfw: nsfw(),
  owner_id: term(),
  parent_id: parent_id(),
  permission_overwrites: permission_overwrites(),
  permissions: term(),
  position: position(),
  rate_limit_per_user: rate_limit_per_user(),
  recipients: term(),
  rtc_region: term(),
  thread_metadata: term(),
  topic: topic(),
  type: type(),
  user_limit: term(),
  video_quality_mode: term()
}

Type 0 partial channel object representing a text channel within a guild.

Link to this type

guild_voice_channel()

View Source

Specs

guild_voice_channel() :: %Nostrum.Struct.Channel{
  application_id: term(),
  bitrate: bitrate(),
  default_auto_archive_duration: term(),
  guild_id: guild_id(),
  icon: term(),
  id: id(),
  last_message_id: term(),
  last_pin_timestamp: term(),
  member: term(),
  member_count: term(),
  message_count: term(),
  name: name(),
  newly_created: term(),
  nsfw: nsfw(),
  owner_id: term(),
  parent_id: parent_id(),
  permission_overwrites: permission_overwrites(),
  permissions: term(),
  position: position(),
  rate_limit_per_user: term(),
  recipients: term(),
  rtc_region: rtc_region(),
  thread_metadata: term(),
  topic: term(),
  type: 2,
  user_limit: user_limit(),
  video_quality_mode: term()
}

Type 2 partial channel object representing an audio channel within a guild.

Link to this type

icon()

View Source

Specs

icon() :: String.t() | nil

The hash of the channels icon.

Link to this type

id()

View Source

Specs

id() :: Nostrum.Snowflake.t()

The id of the channel object.

Link to this type

join_timestamp()

View Source (since 0.5.0)

Specs

join_timestamp() :: DateTime.t()

When the user joined the thread.

Link to this type

last_message_id()

View Source

Specs

last_message_id() :: Nostrum.Struct.Message.id() | nil

The id of the last message sent in the channel.

Link to this type

last_pin_timestamp()

View Source

Specs

last_pin_timestamp() :: DateTime.t() | nil

Timestamp for the last pinned message.

Link to this type

locked()

View Source (since 0.5.0)

Specs

locked() :: boolean()

The threads locked status.

Link to this type

member()

View Source (since 0.5.0)

Specs

member() :: %{
  id: id(),
  user_id: user_id(),
  join_timestamp: join_timestamp(),
  flags: flags()
}

Present when the bot joins a thread.

Note: This is omitted on threads that the bot can immediately access on :GUILD_CREATE events received.

Link to this type

member_count()

View Source (since 0.5.0)

Specs

member_count() :: integer() | nil

Approximate count of members in a thread, capped at 50.

Link to this type

message_count()

View Source (since 0.5.0)

Specs

message_count() :: integer() | nil

Approximate count of messages in a thread, capped at 50.

Link to this type

name()

View Source

Specs

name() :: String.t()

The name of the channel.

Link to this type

newly_created()

View Source (since 0.5.1)

Specs

newly_created() :: boolean() | nil

Included only in the THREAD_CREATE event.

Link to this type

nsfw()

View Source

Specs

nsfw() :: boolean()

Whether the NSFW setting is enabled for this channel.

Link to this type

owner_id()

View Source

Specs

owner_id() :: Nostrum.Struct.User.id()

The id of the user of a group direct message or thread.

This applies to user created channels.

Link to this type

parent_id()

View Source

Specs

parent_id() :: id() | nil

The id of the parent channel that this channel is located under.

For threads, that is the channel that contains the thread. For regular channels, it is the category that the channel is located under.

Link to this type

permission_overwrites()

View Source

Specs

permission_overwrites() :: [Nostrum.Struct.Overwrite.t()]

A list of permission overwrites applied to the channel.

Link to this type

permissions()

View Source (since 0.5.0)

Specs

permissions() :: String.t()

Computed permissions of the invoking user.

Permissions for the invoking user in the channel, including overwrites, only included when part of the resolved data received on a slash command interaction

Link to this type

position()

View Source

Specs

position() :: integer()

The position of the channel in the sidebar of the guild.

Link to this type

rate_limit_per_user()

View Source (since 0.5.0)

Specs

rate_limit_per_user() :: integer() | nil

The users rate limit.

Amount of seconds a user has to wait before sending another message (0-21600); bots, as well as users with the permission manage_messages or manage_channel, are unaffected

Link to this type

recipients()

View Source

Specs

recipients() :: [Nostrum.Struct.User.t()]

A list of users in a group DM.

Link to this type

rtc_region()

View Source (since 0.5.0)

Specs

rtc_region() :: String.t() | nil

Region id for the channel.

More information about region ids can be found on the Discord API Voice Region Object Documentation.

Link to this type

t()

View Source

Specs

t() ::
  guild_text_channel()
  | dm_channel()
  | guild_voice_channel()
  | group_dm_channel()
  | guild_category_channel()
  | guild_news_channel()
  | guild_store_channel()
  | guild_news_thread_channel()
  | guild_public_thread_channel()
  | guild_private_thread_channel()
  | guild_stage_voice_channel()

All valid channel types.

Link to this type

text_channel()

View Source
This type is deprecated. See t.0.

Specs

text_channel() :: guild_text_channel() | dm_channel() | group_dm_channel()

All valid text channels.

Link to this type

thread_metadata()

View Source (since 0.5.0)

Specs

thread_metadata() :: %{
  archived: archived(),
  auto_archive_duration: auto_archive_duration(),
  archive_timestamp: archive_timestamp(),
  locked: boolean()
}

The video quality mode of the voice channel.

More information about video quality modes can be found on the Discord API Video Quality Mode Documentation.

Link to this type

topic()

View Source

Specs

topic() :: String.t()

The topic of the channel.

Link to this type

type()

View Source

Specs

type() :: integer()

The type of channel.

More information about Discord Channel Types can be found under the types on the Discord API Channel Type Documentation.

Link to this type

user_id()

View Source (since 0.5.0)

Specs

user_id() :: Nostrum.Snowflake.t() | nil

User id of the threads creator.

Link to this type

user_limit()

View Source

Specs

user_limit() :: integer()

The user limit of a voice channel.

Link to this type

video_quality_mode()

View Source (since 0.5.0)

Specs

video_quality_mode() :: integer() | nil

The video quality mode of the channel.

More information about video quality modes can be found on the Discord API Video Quality Mode Documentation.

Link to this type

voice_channel()

View Source
This type is deprecated. See t:guild_voice_channel/0.

Specs

voice_channel() :: guild_voice_channel()

A Nostrum.Struct.Channel that represents a voice channel

Link to this section Functions

Link to this function

mention(channel)

View Source

Specs

mention(t()) :: String.t()

Convert a channel into a mention.

Handles the conversion of a Nostrum.Struct.Channel into the required format to mention the channel within a message. Mentioning the channel will provide a clickable link to take the user to the channel.

Parameters

Examples 

Nostrum.Cache.ChannelCache.get(381889573426429952)
|> Nostrum.Struct.Channel.mention()
"<#381889573426429952>"