I'm writing userscripts to interact with Stack Exchange Chat. I'd like to be notified when things happen (e.g. messages added, removed, edited, users joining, etc.). I know that I could use a MutationObserver to watch for changes to the DOM, but is there any way to register a callback with the SE Chat system to be notified upon these events happening?

1 Answer 1


You can register a callback with Stack Exchange Chat, which gets called prior to the change happening in the DOM (i.e. if you want to find a new message in the DOM, you need to use a setTimeout() to act after the DOM change). Callbacks can be registered with CHAT.addEventHandlerHook(callback), which takes a function as its single argument.

Prior to most of the chat system processing of the event, the registered callbacks are executed in the order they were added. If any callback alters the event object in argument 0, then that change will be propagated to any subsequent callbacks and used when the chat system updates the DOM after all registered callbacks have been executed. If any callback returns a truthy value, then no further callbacks are executed and the chat system doesn't do any of its normal processing of the event (i.e. the DOM will not be updated). Effectively, returning a truthy value from a callback cancels the event.

The chat system itself uses CHAT.addEventHandlerHook(callback) to add its own callback for partial processing of some event types. This means that the processing for the following event types will be split between prior to other callbacks and after other callbacks: MessageDeleted, MessageEdited, MessageFlagged, MessagePosted, MessageReply, UserEntered, UserLeft, UserMentioned, and UserNameOrAvatarChanged.

The callback function is passed arguments that look like:

arguments: {
    0: {
        event_type: 1,
        time_stamp: 1552493100,
        content: 'Test message with a tag <a href="//stackoverflow.com/questions/tagged/some-tag"><span class="ob-post-tag" style="background-color: #E0EAF1; color: #3E6D8E; border-color: #3E6D8E; border-style: solid;">some-tag</span></a>.',
        id: 92913194,
        user_id: 3773011,
        user_name: "Makyen",
        room_id: 68414,
        room_name: "SOCVR Testing Facility",
        message_id: 45625173
    1: false,
    2: 92913190

The first argument is a chat "event" Object. This answer on MSE has a list and description of the possible key/value pairs, at least for event_type == 1. The most common key/value pairs which may be included for messages which are not shown above are show_parent and parent_id. The show_parent key is only present if the message is an actual reply to the message ID indicated in parent_id. parent_id will be present for actual replies and @ pings. For @ pings, parent_id will be the most recent message by the pinged user and show_parent won't be present.

The type of event is indicated by the numeric value of event_type. There are 34 types which are possible for event_type.

const chatEventTypes = {
    1: 'MessagePosted',
    2: 'MessageEdited',
    3: 'UserEntered',
    4: 'UserLeft',
    5: 'RoomNameChanged',
    6: 'MessageStarred',
    7: 'DebugMessage',
    8: 'UserMentioned',
    9: 'MessageFlagged',
    10: 'MessageDeleted',
    11: 'FileAdded',
    12: 'ModeratorFlag',
    13: 'UserSettingsChanged',
    14: 'GlobalNotification',
    15: 'AccessLevelChanged',
    16: 'UserNotification',
    17: 'Invitation',
    18: 'MessageReply',
    19: 'MessageMovedOut',
    20: 'MessageMovedIn',
    21: 'TimeBreak',
    22: 'FeedTicker',
    29: 'UserSuspended',
    30: 'UserMerged',
    34: 'UserNameOrAvatarChanged',

The callback will receive events for all the rooms the user is in, so you will want to filter them by matching the room_id to the current room.

The list of event types was copied from the SE's minimized chat JavaScript.

  • can you explain with a more detailed example? When I use it it appears n[o] is not a function. Thanks!
    – lois6b
    Mar 14, 2019 at 14:25
  • 1
    @lois6b Sure, I'll work up a complete example. I may not get to it today. However, I'm not sure where your error of n[o] is not a function came from. If that's the complete error, then it sounds like it's from SE's minimized code.
    – Makyen
    Mar 14, 2019 at 15:08

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .