Event Catalog Reference

Copy Markdown View Source

This page lists the normalized events from BaileysEx.subscribe/2 and the raw event keys from BaileysEx.subscribe_raw/2.

Normalized subscribe/2 events

{:connection, update}

  • Type: {:connection, map()}
  • Default: emitted when :connection_update exists
  • Example:
{:connection, %{connection: :open}}

Use this for connection lifecycle updates, QR data, and disconnect metadata.

{:message, message}

  • Type: {:message, map()}
  • Default: emitted once per entry in :messages_upsert.messages
  • Example:
{:message, %{key: %{remote_jid: "15551234567@s.whatsapp.net"}}}

Use this for bot and automation message handling.

{:presence, update}

  • Type: {:presence, map()}
  • Default: emitted when :presence_update exists
  • Example:
{:presence, %{id: "15551234567@s.whatsapp.net", presences: %{}}}

Use this for contact and group presence updates.

{:call, payload}

  • Type: {:call, map() | list() | term()}

  • Default: emitted when :call exists
  • Example:
{:call, %{status: :offer}}

Use this when you want call offer, accept, reject, or terminate events.

{:event, name, payload}

  • Type: {:event, atom(), term()}
  • Default: emitted for every other raw event
  • Example:
{:event, :groups_update, [%{id: "120363001234567890@g.us"}]}

Use this for everything the public facade does not normalize directly.

Raw subscribe_raw/2 events

Each raw delivery is a map with one or more of these keys.

Connection and auth

:connection_update

  • Type: map()
  • Default: emitted by the runtime during connect, pair, reconnect, and close flows
  • Example:
%{connection_update: %{connection: :open}}

Connection lifecycle, QR data, and disconnect details.

Close updates include a Baileys-shaped disconnect payload under last_disconnect:

%{
  connection_update: %{
    connection: :close,
    last_disconnect: %{
      error: %{reason: :logged_out, status_code: 401, message: "Logged Out"},
      date: ~U[2026-03-16 12:00:00Z]
    }
  }
}

:creds_update

  • Type: map()
  • Default: emitted whenever the runtime updates auth credentials
  • Example:
%{creds_update: %{me: %{name: "Example"}}}

Persist this if you want your session to survive restarts.

:socket_node

  • Type: BaileysEx.BinaryNode.t() | map()

  • Default: emitted for selected low-level socket traffic
  • Example:
%{socket_node: node}

Useful for advanced debugging.

Chats and contacts

:chats_upsert

  • Type: list()
  • Default: emitted for new chats
  • Example:
%{chats_upsert: [%{id: "15551234567@s.whatsapp.net"}]}

:chats_update

  • Type: list()
  • Default: emitted for chat state changes
  • Example:
%{chats_update: [%{id: "15551234567@s.whatsapp.net", archived: true}]}

:chats_delete

  • Type: list()
  • Default: emitted when chats are removed
  • Example:
%{chats_delete: ["15551234567@s.whatsapp.net"]}

:chats_lock

  • Type: term()
  • Default: emitted for chat lock updates
  • Example:
%{chats_lock: payload}

:contacts_upsert

  • Type: list()
  • Default: emitted for new or full contact inserts
  • Example:
%{contacts_upsert: [%{id: "15551234567@s.whatsapp.net"}]}

:contacts_update

  • Type: list()
  • Default: emitted for contact changes
  • Example:
%{contacts_update: [%{id: "15551234567@s.whatsapp.net", notify: "Jeff"}]}

:blocklist_set

  • Type: list()
  • Default: emitted when the runtime receives the full blocklist
  • Example:
%{blocklist_set: ["15551234567@s.whatsapp.net"]}

:blocklist_update

  • Type: list()
  • Default: emitted for incremental blocklist updates
  • Example:
%{blocklist_update: [%{jid: "15551234567@s.whatsapp.net", action: :block}]}

Messages and media

:messages_upsert

  • Type: %{type: atom() | String.t(), messages: list()}

  • Default: emitted when messages arrive or are inserted from history sync
  • Example:
%{messages_upsert: %{type: :notify, messages: [%{key: %{id: "ABC"}}]}}

:messages_update

  • Type: list()
  • Default: emitted for message edits and status updates
  • Example:
%{messages_update: [%{key: %{id: "ABC"}}]}

:messages_delete

  • Type: list()
  • Default: emitted when messages are revoked or removed
  • Example:
%{messages_delete: [%{key: %{id: "ABC"}}]}

:messages_reaction

  • Type: list()
  • Default: emitted for reaction updates
  • Example:
%{messages_reaction: [%{key: %{id: "ABC"}, reaction: "🔥"}]}

:messages_media_update

  • Type: list()
  • Default: emitted for media retry and download updates
  • Example:
%{messages_media_update: [%{key: %{id: "ABC"}}]}

:message_receipt_update

  • Type: list()
  • Default: emitted for delivery and read receipts
  • Example:
%{message_receipt_update: [%{key: %{id: "ABC"}}]}

:messaging_history_set

  • Type: map()
  • Default: emitted when a history-sync batch is applied
  • Example:
%{messaging_history_set: %{messages: []}}

Groups, communities, labels, and settings

:groups_upsert

  • Type: list()
  • Default: emitted when groups are inserted
  • Example:
%{groups_upsert: [%{id: "120363001234567890@g.us"}]}

:groups_update

  • Type: list()
  • Default: emitted for group and community metadata changes
  • Example:
%{groups_update: [%{id: "120363001234567890@g.us", subject: "Launch Team"}]}

:group_participants_update

  • Type: list() | map()

  • Default: emitted for participant add, remove, promote, or demote updates
  • Example:
%{group_participants_update: [%{id: "120363001234567890@g.us"}]}

:group_join_request

  • Type: map() | list()

  • Default: emitted for join-approval updates
  • Example:
%{group_join_request: %{id: "120363001234567890@g.us"}}

:group_member_tag_update

  • Type: list() | map()

  • Default: emitted for member-tag updates
  • Example:
%{group_member_tag_update: [%{id: "120363001234567890@g.us"}]}

:labels_edit

  • Type: list()
  • Default: emitted for label create, update, and delete actions
  • Example:
%{labels_edit: [%{id: "1", name: "Important"}]}

:labels_association

  • Type: list()
  • Default: emitted when labels are associated with chats or messages
  • Example:
%{labels_association: [%{label_id: "1"}]}

:settings_update

  • Type: map() | list()

  • Default: emitted for app settings updates
  • Example:
%{settings_update: %{unarchive_chats: true}}

:dirty_update

  • Type: map()
  • Default: emitted when WhatsApp asks the client to refetch a dataset
  • Example:
%{dirty_update: %{type: "groups"}}

:lid_mapping_update

  • Type: list() | map()

  • Default: emitted when LID mappings change
  • Example:
%{lid_mapping_update: [%{pn: "15551234567", lid: "123@lid"}]}

Presence, calls, and newsletters

:presence_update

  • Type: map()
  • Default: emitted for presence and chatstate updates
  • Example:
%{presence_update: %{id: "15551234567@s.whatsapp.net", presences: %{}}}

:call

  • Type: map() | list()

  • Default: emitted for call offers and terminal call states
  • Example:
%{call: %{status: :offer}}

:newsletter_participants_update

  • Type: map() | list()

  • Default: emitted for newsletter participant changes
  • Example:
%{newsletter_participants_update: %{jid: "120363400000000000@newsletter"}}

:newsletter_reaction

  • Type: map() | list()

  • Default: emitted for newsletter reaction updates
  • Example:
%{newsletter_reaction: %{jid: "120363400000000000@newsletter"}}

:newsletter_settings_update

  • Type: map() | list()

  • Default: emitted for newsletter settings changes
  • Example:
%{newsletter_settings_update: %{jid: "120363400000000000@newsletter"}}

:newsletter_view

  • Type: map() | list()

  • Default: emitted for newsletter view and metadata updates
  • Example:
%{newsletter_view: %{jid: "120363400000000000@newsletter"}}