View Source Nostrum.Consumer behaviour (Nostrum v0.6.1)

Consumer process for gateway event handling.

Consuming Gateway Events

To handle events, Nostrum uses a GenStage implementation.

Nostrum defines the producer and producer_consumer in the GenStage design. To consume the events you must create at least one consumer process. It is generally recommended that you spawn a consumer per core. To find this number you can use System.schedulers_online/0.

Nostrum uses a ConsumerSupervisor to dispatch events, meaning your handlers will each be ran in their own separate task.

Example

An example consumer can be found here.

Link to this section Summary

Types

Dispatched when a channel is created.

Dispatched when a channel is updated.

Dispatched when a guild member is updated.

Dispatched when a role on a guild is updated.

Different from guild_integrations_update/0 in that more than only the guild_id is provided

General process options.

Dispatched when a user's presence is updated.

Dispatched when a thread is created or when added to a private thread

Dispatched when a thread is deleted, if the thread was cached, contains the original thread, otherwise contains :noop

Dispatched when gaining access to a channel

Dispatched when a ThreadMember for the current user is updated

Dispatched when member(s) are added or removed from a thread

Dispatched when a user is updated.

Dispatched when async listening is enabled and another user is actively speaking

Dispatched when the bot is ready to begin sending audio after joining a voice channel

Dispatched when the bot starts or stops speaking

Callbacks

Callback used to handle events.

Functions

Starts a consumer process.

Link to this section Types

Specs

channel_create() ::
  {:CHANNEL_CREATE, Nostrum.Struct.Channel.t(), Nostrum.Struct.WSState.t()}

Dispatched when a channel is created.

Starting from API and Gateway V8, this will never be sent for a DM.

Specs

channel_delete() ::
  {:CHANNEL_DELETE, Nostrum.Struct.Channel.t(), Nostrum.Struct.WSState.t()}

Specs

channel_pins_ack() :: {:CHANNEL_PINS_ACK, map(), Nostrum.Struct.WSState.t()}

Specs

channel_pins_update() ::
  {:CHANNEL_PINS_UPDATE, Nostrum.Struct.Event.ChannelPinsUpdate.t(),
   Nostrum.Struct.WSState.t()}

Specs

channel_update() ::
  {:CHANNEL_UPDATE,
   {old_channel :: Nostrum.Struct.Channel.t() | nil,
    new_channel :: Nostrum.Struct.Channel.t()}, Nostrum.Struct.WSState.t()}

Dispatched when a channel is updated.

old_channel will be nil when the pre-update channel could not be fetched from the cache.

Specs

Specs

guild_available() ::
  {:GUILD_AVAILABLE, new_guild :: Nostrum.Struct.Guild.t(),
   Nostrum.Struct.WSState.t()}

Specs

guild_ban_add() ::
  {:GUILD_BAN_ADD, Nostrum.Struct.Event.GuildBanAdd.t(),
   Nostrum.Struct.WSState.t()}

Specs

guild_ban_remove() ::
  {:GUILD_BAN_REMOVE, Nostrum.Struct.Event.GuildBanRemove.t(),
   Nostrum.Struct.WSState.t()}

Specs

guild_create() ::
  {:GUILD_CREATE, new_guild :: Nostrum.Struct.Guild.t(),
   Nostrum.Struct.WSState.t()}

Specs

guild_delete() ::
  {:GUILD_DELETE,
   {old_guild :: Nostrum.Struct.Guild.t(), unavailable :: boolean()},
   Nostrum.Struct.WSState.t()}

Specs

guild_emojis_update() ::
  {:GUILD_EMOJIS_UPDATE,
   {guild_id :: integer(), old_emojis :: [Nostrum.Struct.Emoji.t()],
    new_emojis :: [Nostrum.Struct.Emoji.t()]}, Nostrum.Struct.WSState.t()}
Link to this type

guild_integrations_update()

View Source

Specs

guild_integrations_update() ::
  {:GUILD_INTEGRATIONS_UPDATE, Nostrum.Struct.Event.GuildIntegrationsUpdate.t(),
   Nostrum.Struct.WSState.t()}

Specs

guild_member_add() ::
  {:GUILD_MEMBER_ADD,
   {guild_id :: integer(), new_member :: Nostrum.Struct.Guild.Member.t()},
   Nostrum.Struct.WSState.t()}

Specs

guild_member_remove() ::
  {:GUILD_MEMBER_REMOVE,
   {guild_id :: integer(), old_member :: Nostrum.Struct.Guild.Member.t()},
   Nostrum.Struct.WSState.t()}

Specs

guild_member_update() ::
  {:GUILD_MEMBER_UPDATE,
   {guild_id :: integer(), old_member :: Nostrum.Struct.Guild.Member.t() | nil,
    new_member :: Nostrum.Struct.Guild.Member.t()}, Nostrum.Struct.WSState.t()}

Dispatched when a guild member is updated.

old_member will be nil when the pre-update member could not be fetched from the cache.

Specs

guild_members_chunk() ::
  {:GUILD_MEMBERS_CHUNK, map(), Nostrum.Struct.WSState.t()}

Specs

guild_role_create() ::
  {:GUILD_ROLE_CREATE,
   {guild_id :: integer(), new_role :: Nostrum.Struct.Guild.Role.t()},
   Nostrum.Struct.WSState.t()}

Specs

guild_role_delete() ::
  {:GUILD_ROLE_DELETE,
   {guild_id :: integer(), old_role :: Nostrum.Struct.Guild.Role.t()},
   Nostrum.Struct.WSState.t()}

Specs

guild_role_update() ::
  {:GUILD_ROLE_UPDATE,
   {guild_id :: integer(), old_role :: Nostrum.Struct.Guild.Role.t() | nil,
    new_role :: Nostrum.Struct.Guild.Role.t()}, Nostrum.Struct.WSState.t()}

Dispatched when a role on a guild is updated.

old_role will be nil when the pre-update role could not be fetched from the cache.

Link to this type

guild_scheduled_event_create()

View Source

Specs

guild_scheduled_event_create() ::
  {:GUILD_SCHEDULED_EVENT_CREATE, Nostrum.Struct.Guild.ScheduledEvent.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

guild_scheduled_event_delete()

View Source

Specs

guild_scheduled_event_delete() ::
  {:GUILD_SCHEDULED_EVENT_DELETE, Nostrum.Struct.Guild.ScheduledEvent.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

guild_scheduled_event_update()

View Source

Specs

guild_scheduled_event_update() ::
  {:GUILD_SCHEDULED_EVENT_UPDATE, Nostrum.Struct.Guild.ScheduledEvent.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

guild_scheduled_event_user_add()

View Source

Specs

guild_scheduled_event_user_add() ::
  {:GUILD_SCHEDULED_EVENT_USER_ADD,
   Nostrum.Struct.Event.GuildScheduledEventUserAdd.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

guild_scheduled_event_user_remove()

View Source

Specs

guild_scheduled_event_user_remove() ::
  {:GUILD_SCHEDULED_EVENT_USER_REMOVE,
   Nostrum.Struct.Event.GuildScheduledEventUserRemove.t(),
   Nostrum.Struct.WSState.t()}

Specs

guild_unavailable() ::
  {:GUILD_UNAVAILABLE,
   unavailable_guild :: Nostrum.Struct.Guild.UnavailableGuild.t(),
   Nostrum.Struct.WSState.t()}

Specs

guild_update() ::
  {:GUILD_UPDATE,
   {old_guild :: Nostrum.Struct.Guild.t(),
    new_guild :: Nostrum.Struct.Guild.t()}, Nostrum.Struct.WSState.t()}
Link to this type

integration_create()

View Source (since 0.5.1)

Specs

integration_create() ::
  {:INTEGRATION_CREATE, Nostrum.Struct.Guild.Integration.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

integration_delete()

View Source (since 0.5.1)

Specs

integration_delete() ::
  {:INTEGRATION_DELETE, Nostrum.Struct.Event.GuildIntegrationDelete.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

integration_update()

View Source (since 0.5.1)

Specs

integration_update() ::
  {:INTEGRATION_UPDATE, Nostrum.Struct.Guild.Integration.t(),
   Nostrum.Struct.WSState.t()}

Different from guild_integrations_update/0 in that more than only the guild_id is provided

Specs

interaction_create() ::
  {:INTERACTION_CREATE, Nostrum.Struct.Interaction.t(),
   Nostrum.Struct.WSState.t()}

Specs

message_ack() :: {:MESSAGE_ACK, map(), Nostrum.Struct.WSState.t()}

Specs

message_create() ::
  {:MESSAGE_CREATE, message :: Nostrum.Struct.Message.t(),
   Nostrum.Struct.WSState.t()}

Specs

message_delete() ::
  {:MESSAGE_DELETE, Nostrum.Struct.Event.MessageDelete.t(),
   Nostrum.Struct.WSState.t()}

Specs

message_delete_bulk() ::
  {:MESSAGE_DELETE_BULK, Nostrum.Struct.Event.MessageDeleteBulk.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

message_reaction_add()

View Source

Specs

message_reaction_add() ::
  {:MESSAGE_REACTION_ADD, Nostrum.Struct.Event.MessageReactionAdd.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

message_reaction_remove()

View Source

Specs

message_reaction_remove() ::
  {:MESSAGE_REACTION_REMOVE, Nostrum.Struct.Event.MessageReactionRemove.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

message_reaction_remove_all()

View Source

Specs

message_reaction_remove_all() ::
  {:MESSAGE_REACTION_REMOVE_ALL,
   Nostrum.Struct.Event.MessageReactionRemoveAll.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

message_reaction_remove_emoji()

View Source

Specs

message_reaction_remove_emoji() ::
  {:MESSAGE_REACTION_REMOVE_EMOJI,
   Nostrum.Struct.Event.MessageReactionRemoveEmoji.t(),
   Nostrum.Struct.WSState.t()}

Specs

message_update() ::
  {:MESSAGE_UPDATE, updated_message :: Nostrum.Struct.Message.t(),
   Nostrum.Struct.WSState.t()}

Specs

option() ::
  {:registry, atom()}
  | {:name, Supervisor.name()}
  | {:max_restarts, non_neg_integer()}
  | {:max_seconds, non_neg_integer()}
  | {:subscribe_to, [GenStage.stage() | {GenStage.stage(), keyword()}]}

General process options.

The subscribe_to option should only be set if you want to use your own producer or producer consumer.

Specs

options() :: [option()] | []

Specs

presence_update() ::
  {:PRESENCE_UPDATE,
   {guild_id :: integer(), old_presence :: map() | nil, new_presence :: map()},
   Nostrum.Struct.WSState.t()}

Dispatched when a user's presence is updated.

old_presence will be nil when the pre-update presence could not be fetched from the cache.

Specs

Specs

resumed() :: {:RESUMED, map(), Nostrum.Struct.WSState.t()}

Specs

thread_create() ::
  {:THREAD_CREATE, Nostrum.Struct.Channel.t(), Nostrum.Struct.WSState.t()}

Dispatched when a thread is created or when added to a private thread

Specs

thread_delete() ::
  {:THREAD_DELETE, Nostrum.Struct.Channel.t() | :noop,
   Nostrum.Struct.WSState.t()}

Dispatched when a thread is deleted, if the thread was cached, contains the original thread, otherwise contains :noop

Specs

thread_list_sync() ::
  {:THREAD_LIST_SYNC, Nostrum.Struct.Event.ThreadListSync.t(),
   Nostrum.Struct.WSState.t()}

Dispatched when gaining access to a channel

Link to this type

thread_member_update()

View Source

Specs

thread_member_update() ::
  {:THREAD_MEMBER_UPDATE, Nostrum.Struct.ThreadMember.t(),
   Nostrum.Struct.WSState.t()}

Dispatched when a ThreadMember for the current user is updated

Link to this type

thread_members_update()

View Source

Specs

thread_members_update() ::
  {:THREAD_MEMBERS_UPDATE, Nostrum.Struct.Event.ThreadMembersUpdate.t(),
   Nostrum.Struct.WSState.t()}

Dispatched when member(s) are added or removed from a thread

Specs

thread_update() ::
  {:THREAD_UPDATE,
   {old_thread :: Nostrum.Struct.Channel.t() | nil,
    new_thread :: Nostrum.Struct.Channel.t()}, Nostrum.Struct.WSState.t()}

Specs

typing_start() ::
  {:TYPING_START, Nostrum.Struct.Event.TypingStart.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

user_settings_update()

View Source

Specs

user_settings_update() :: no_return()

Specs

user_update() ::
  {:USER_UPDATE,
   {old_user :: Nostrum.Struct.User.t() | nil,
    new_user :: Nostrum.Struct.User.t()}, Nostrum.Struct.WSState.t()}

Dispatched when a user is updated.

old_user will be nil when the pre-update user could not be fetched from the cache.

Link to this type

voice_incoming_packet()

View Source (since 0.6.0)

Specs

voice_incoming_packet() ::
  {:VOICE_INCOMING_PACKET, Nostrum.Voice.rtp_opus(),
   Nostrum.Struct.VoiceWSState.t()}

Dispatched when async listening is enabled and another user is actively speaking

The second tuple element is an Nostrum.Voice.rtp_opus/0, which is a tuple with RTP header information and an opus packet. While someone is actively talking, you can expect about 50 events per second per speaking user.

Note that the third tuple element is of type Nostrum.Struct.VoiceWSState.t/0 instead of Nostrum.Struct.WSState.t/0. That struct contains a Nostrum.Struct.VoiceWSState.ssrc_map/0 that can determine the speaking user based on the SSRC.

Link to this type

voice_ready()

View Source (since 0.5.0)

Specs

Dispatched when the bot is ready to begin sending audio after joining a voice channel

Note that the third tuple element is of type Nostrum.Struct.VoiceWSState.t/0 instead of Nostrum.Struct.WSState.t/0.

Specs

voice_server_update() ::
  {:VOICE_SERVER_UPDATE, Nostrum.Struct.Event.VoiceServerUpdate.t(),
   Nostrum.Struct.WSState.t()}
Link to this type

voice_speaking_update()

View Source

Specs

voice_speaking_update() ::
  {:VOICE_SPEAKING_UPDATE, Nostrum.Struct.Event.SpeakingUpdate.t(),
   Nostrum.Struct.VoiceWSState.t()}

Dispatched when the bot starts or stops speaking

Note that the third tuple element is of type Nostrum.Struct.VoiceWSState.t/0 instead of Nostrum.Struct.WSState.t/0.

Specs

voice_state_update() ::
  {:VOICE_STATE_UPDATE, Nostrum.Struct.Event.VoiceState.t(),
   Nostrum.Struct.WSState.t()}

Specs

webhooks_update() :: {:WEBHOOKS_UPDATE, map(), Nostrum.Struct.WSState.t()}

Link to this section Callbacks

Specs

handle_event(event()) :: any()

Callback used to handle events.

Event

event is a tuple describing the event. The tuple will include information in the following format:

{event_name, {event_payload(s)}, WSState.t}

For example, a message create will look like this

{:MESSAGE_CREATE, {Nostrum.Struct.Message.t}, WSState.t}

In some cases there will be multiple payloads when something is updated, so as to include the new and the old versions. In the event of there being two payloads, the old payload will always be first, followed by the new payload.

{:USER_UPDATE, {old_user :: Nostrum.Struct.User.t, new_user :: Nostrum.Struct.User.t}, WSState.t()}

For a full listing of events, please see Nostrum.Consumer.event/0.

Link to this section Functions

Link to this function

start_link(mod, opts \\ [])

View Source

Specs

start_link(module(), options()) :: Supervisor.on_start()

Starts a consumer process.

mod is the name of the module where you define your event callbacks, which should probably be the current module which you can get with __MODULE__.

opts is a list of general process options. See Nostrum.Consumer.options/0 for more info.