View Source Nostrum.Consumer behaviour (Nostrum v0.6.0)
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
event() :: channel_create() | channel_delete() | channel_update() | channel_pins_ack() | channel_pins_update() | guild_ban_add() | guild_ban_remove() | guild_create() | guild_available() | guild_unavailable() | guild_update() | guild_delete() | guild_emojis_update() | guild_integrations_update() | guild_member_add() | guild_members_chunk() | guild_member_remove() | guild_member_update() | guild_role_create() | guild_role_delete() | guild_role_update() | integration_create() | integration_delete() | integration_update() | interaction_create() | message_create() | message_delete() | message_delete_bulk() | message_update() | message_reaction_add() | message_reaction_remove() | message_reaction_remove_all() | message_ack() | presence_update() | ready() | resumed() | thread_create() | thread_delete() | thread_update() | thread_list_sync() | thread_member_update() | thread_members_update() | typing_start() | user_settings_update() | user_update() | voice_ready() | voice_speaking_update() | voice_incoming_packet() | voice_state_update() | voice_server_update() | webhooks_update()
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()}
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.
Specs
guild_scheduled_event_create() ::
{:GUILD_SCHEDULED_EVENT_CREATE, Nostrum.Struct.Guild.ScheduledEvent.t(),
Nostrum.Struct.WSState.t()}
Specs
guild_scheduled_event_delete() ::
{:GUILD_SCHEDULED_EVENT_DELETE, Nostrum.Struct.Guild.ScheduledEvent.t(),
Nostrum.Struct.WSState.t()}
Specs
guild_scheduled_event_update() ::
{:GUILD_SCHEDULED_EVENT_UPDATE, Nostrum.Struct.Guild.ScheduledEvent.t(),
Nostrum.Struct.WSState.t()}
Specs
guild_scheduled_event_user_add() ::
{:GUILD_SCHEDULED_EVENT_USER_ADD,
Nostrum.Struct.Event.GuildScheduledEventUserAdd.t(),
Nostrum.Struct.WSState.t()}
Specs
guild_scheduled_event_user_remove() ::
{:GUILD_SCHEDULED_EVENT_USER_REMOVE,
Nostrum.Struct.Event.GuildScheduledEventUserRemove.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()}
Specs
integration_create() ::
{:INTEGRATION_CREATE, Nostrum.Struct.Guild.Integration.t(),
Nostrum.Struct.WSState.t()}
Specs
integration_delete() ::
{:INTEGRATION_DELETE, Nostrum.Struct.Event.GuildIntegrationDelete.t(),
Nostrum.Struct.WSState.t()}
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()}
Specs
message_reaction_add() ::
{:MESSAGE_REACTION_ADD, Nostrum.Struct.Event.MessageReactionAdd.t(),
Nostrum.Struct.WSState.t()}
Specs
message_reaction_remove() ::
{:MESSAGE_REACTION_REMOVE, Nostrum.Struct.Event.MessageReactionRemove.t(),
Nostrum.Struct.WSState.t()}
Specs
message_reaction_remove_all() ::
{:MESSAGE_REACTION_REMOVE_ALL,
Nostrum.Struct.Event.MessageReactionRemoveAll.t(),
Nostrum.Struct.WSState.t()}
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
ready() :: {:READY, Nostrum.Struct.Event.Ready.t(), Nostrum.Struct.WSState.t()}
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
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
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()}
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.
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.
Specs
voice_ready() ::
{:VOICE_READY, Nostrum.Struct.Event.VoiceReady.t(),
Nostrum.Struct.VoiceWSState.t()}
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()}
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
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
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.