Skip to content

API Stream Message Reference

Jump to bottom
James Wheare edited this page Mar 8, 2018 · 27 revisions

Overview • RPC Reference

Messages are JSON objects.

The messages listed here are the bare minimum needed to control application state. There are many more not listed that are for logging purposes only. Templating guidance should appear here eventually.

# Common message attributes

  • type - (str) message type. message handlers should switch on this value
  • cid - (int) connection id (globally unique across all users)
  • bid - (int) buffer id (globally unique across all users)
  • eid - (int) buffer event id (unique per buffer) this doubles as a microsecond precision timestamp

If an attribute doesn't make sense in the context of a specific message, it will either be absent from the message or its value will be -1.

# Table of Contents

# header

Indicates the start of the stream. You can use the time value to determine any time difference between the server and client.

  • time - (int UNIX timestamp in seconds) current server time
  • idle_interval - (int milliseconds) maximum time between messages
  • streamid - (str) unique identifier for this stream connection
  • resumed - (bool) whether the stream has been resumed or not
  • accrued - (int) number of messages in a resumed stream

# idle

Just used to keep messages flowing on the stream

# stat_user

The authenticated user's name, account details, settings and preferences. You'll receive this message at any point in a stream session to be notified of updates to any of its values.

  • id - (int) user id
  • name - (str) real name
  • email - (str) email address
  • verified - (bool) have they verified their email address?
  • last_selected_bid - (int) last buffer they had open. this should be the first buffer to select on session restore
  • limits_name - (str free|trial|unlimited) keyword for their subscription plan
  • limits - (obj) subscription plan details:
    • networks - (int) limit for number of external connections they can make
    • passworded_servers - (bool) can they connected to passworded networks?
    • zombiehours - (int) how long after they close their last session before they get disconnected
    • download_logs - (bool) (unused) can they download logs?
    • maxhistorydays - (int) (unused) how many days of logs do we store
  • num_connections - (int) total number of connections on their account
  • num_active_connections - (int) number of connections that are connected
  • highlights - (array of str) words that trigger a highlight notification
  • prefs - (JSON str to parse) various UI specific display settings:
    • channel-hiddenMembers - (obj map bid => bool) should we hide the members list for a channel by default? (only if UI relevant)
    • channel-disableTrackUnread - (obj map bid => bool) should we mark a channel as unread in the message list?
    • buffer-disableTrackUnread - (obj map bid => bool) should we mark a buffer as unread in the message list?
    • channel-hideJoinPart - (obj map bid => bool) should we hide join/part events in a channel completely?
    • buffer-hideJoinPart - (obj map bid => bool) should we hide join/part events in a buffer completely?
    • channel-inlineimages - (obj map bid => bool) should we allow inline images to render in this channel? (only if feature is enabled)
    • buffer-inlineimages - (obj map bid => bool) should we allow inline images to render in this buffer? (only if feature is enabled)
    • hideInviteBadge - (bool) should we show how many invites they have left alongside the link to send invites?
    • time-24hr - (bool) should we use a 24 hour clock for timestamps?
    • time-seconds - (bool) should we display timestamps with seconds?
    • mode-showsymbol - (bool) should we show full mode symbols (@, +, etc) instead of just coloured dots?
    • nick-colors - (bool) should we colourise nicknames
  • join_date - (int UNIX timestamp in seconds) signup date
  • autoaway - (bool) should we mark them away after they close their last session?

# num_invites

How many invites a user has remaining

  • num_invites - (int) invite count

# oob_include

  • url - (str) URL to fetch the backlog from. Has a short expiry and should be fetched immediately. The stream will close when it expires.
  • timeout - (int) expiry time in ms

# oob_timeout

Send when the oob_include timeout is reached, before the stream is closed

  • timeout - (int) expiry time in ms

# oob_skipped

Sent when the backlog is inlined instead of prepared out of band.

# backlog_starts

Marks the start of the oob_include.

  • numbuffers - (int) number of makebuffer messages in the backlog. Useful for starting a progress bar

# backlog_complete

Marks the end of the oob_include.

# makeserver

Marks the start of a connection backlog block

  • cid - (int) connection id
  • hostname - (str) connection hostname
  • port - (int) connection port
  • ssl - (bool) is this connection using ssl?
  • name - (str) connection display name
  • nick - (str) user's nick on this connection
  • realname - (str) the user's real name on this connection
  • server_pass - (str) connection password
  • nickserv_pass - (str) nickserv password in use on this connection
  • join_commands - (str|null) IRC commands to execute on connect
  • ignores - (array) list of user hostmasks whos messages should be hidden
  • away - (str|bool) user's away status on this connection
  • status - (str) connection status. see status_changed
  • fail_info - (obj) connection failure info. see status_changed
  • ircserver - (str) fully resolved IRC server hostname
  • ident_prefix - (str) if the username has been ident verified this will be ~ otherwise blank.
  • user - (str) connection username (automatically chosen and unchangeable, takes the form users.<uid>)
  • userhost - (str) connection origin host (depends on which pool this connection is on)
  • usermask - (str) full usermask: <ident_prefix><user>@<userhost>
  • num_buffers - (int) buffer count
  • disconnected - [deprecated] see status_changed

# end_of_backlog

Marks the end of a connection backlog block

  • cid - (int) connection id

# makebuffer

Information for a connection buffer

  • cid - (int) connection id
  • bid - (int) buffer id
  • buffer_type - (str)
    • console (server log)
    • channel
    • conversation
  • name - (str) buffer name
  • deferred - (bool) when true, no events will be included in the backlog, and must only be fetched via a backlog API call when needed.
  • timeout - (bool) this is a special case of deferred that indicates the server timed out fetching backlog for this buffer. This can lead to hidden highlights in joined channels and conversations. Clients should fetch the backlog immediately.
  • archived - (bool) when true, this buffer should be display less prominently in the buffer list.
  • min_eid - (int eid) earliest event id available on the server
  • created - (int UNIX timestamp in microseconds) buffer creation date
  • last_seen_eid - (int eid) used in calculating unread status for a buffer
  • max_eid - [deprecated] use backlog

# channel_init

Information for a joined channel

  • cid - (int) connection id
  • bid - (int) buffer id
  • chan - (str) target buffer name
  • members - (array of member objects)
    • nick - (str) member nick
    • realname - (str) member real name
    • ircserver - (str) IRC host from where member is connected to the network
    • mode - (str) member's mode on this channel
    • hopcount - (int) number of server hops away from the connection user
    • away - (bool) is the member away?
    • ident_prefix, user, userhost, usermask - (str) member usermask details
  • mode - (str) channel mode string
  • ops - (obj) parametric arrays of objects with mode and param values required to build the mode string. this form is also used for channel_mode, channel_mode_is and user_channel_mode messages
    • add - (array of obj {"mode":<mode_letter>, "param":<mode_value>})
    • remove - same as add
  • topic (obj)
    • text - (str) channel topic
    • time - (int UNIX timestamp in seconds) topic set date
    • nick - (str) topic author
    • ident_prefix, user, userhost, usermask - (str) topic author usermask details
  • timestamp - (int UNIX timestamp in seconds) channel creation date
  • channel_type - (str) type of channel, will usually be public
    • public
    • private
    • secret
  • url - (str) channel url

# status_changed

Current status of a connection

  • cid - (int) connection id
  • old_status - (str) previous status
  • new_status - (str) current status
  • fail_info - (obj) any extra metadata about a failed connection

Statuses

  • queued
  • connecting
  • connected
  • connected_joining
  • connected_ready
  • quitting
  • disconnected
  • waiting_to_retry
  • ip_retry

Fail info

If a connection status unexpectedly changes to disconnected, it will immediately transition to waiting_to_retry and the fail_info object will be populated with the following values:

  • type - (str) keyword indicating type of disconnect
    • connecting_restricted - user's subscription level restricted this connection
    • socket_closed - connected network went down
    • connecting_failed - network connection couldn't be established
    • killed - connection forcible killed by the IRC server
  • reason - (str) keyword or string to be shown to the user
    • pool_lost - Connection pool failed
    • no_pool - No available connection pools
    • enetdown - Network down
    • etimedout - Timed out
    • timeout - Timed out
    • ehostunreach - Host unreachable
    • econnrefused - Connection refused
    • nxdomain - Invalid hostname
    • ssl_certificate_error - SSL certificate error
    • ssl_error - SSL error
    • crash - Connection crashed
  • timestamp - (int UNIX timestamp in seconds) when the disconnect occured
  • retry_timeout - (int seconds) add this to timestamp to determine when the connection will retry
  • attempts - (int) number of retry attempts made so far

Once a certain number of failed attempts have been made, the server will give up, at which point the status will remain at disconnected and fail_info will contain a give_up value of true.

A status of ip_retry indicates that this connection's hostname resolved to multiple IP addresses, and the server is now retrying on a new IP. fail_info will contain the error text (error) and the failed IPv4/6 address (ip)

# heartbeat_echo

Sent to all stream clients when a heartbeat API call is received.

  • seenEids - (str JSON map cid => bid => eid) maximum seen eid for a buffer. use this to keep the last_seen_eid value from makebuffer in sync. ignore any eids lower than the client's local value.

# buffer_msg

Regular chat message in a buffer

  • cid - (int) connection id
  • bid - (int) buffer id
  • chan - (str) target buffer name
  • eid - (int) event id
  • msg - (str) message text
  • from - (str) message author
  • ident_prefix - (str) if the message author has been ident verified this will be ~ otherwise blank.
  • from_name - (str) message author username
  • from_host - (str) message author origin host
  • hostmask - (str) full usermask: <ident_prefix><from_name>@<from_host>
  • from_mode - (str) message author channel mode at time of message
  • from_account - (str) message author account name at time of message
  • from_realname - (str) message author realname at time of message
  • self - (bool) was this message sent from the connection user?
  • highlight - (bool) does this message mention the connection user or trigger a highlight word?

# buffer_me_msg

/me style action message in a buffer

Message values same as buffer_msg

# notice

/notice message in a buffer

Message values same as buffer_msg

Channel notices are sent to the console buffer as well as the target channel. In this case, the bid won't tell you where it was intended. Some extra message values help here:

  • target - (str) target buffer name
  • to_chan - (bool) intended target is a channel

If to_chan is true, use the target value only when rendering the notice in a console buffer.

# channel_timestamp

A channel's creation time. In an initialized channel context, set the channel timestamp.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • timestamp - (int UNIX timestamp in seconds) channel creation date

# channel_url

A channel's URL. In an initialized channel context, set the channel URL.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • url - (str) channel URL

# channel_topic

A channel's topic has been set. In an initialized channel context, set the channel topic.

  • cid - (int) connection id
  • bid - (int) buffer id
  • chan - (str) channel name
  • eid - (int) event id
  • topic - (str) topic text
  • topic_time - (int UNIX timestamp in seconds) topic set date
  • author - (str) topic author nickname
  • ident_prefix - (str) if the topic author has been ident verified this will be ~ otherwise blank.
  • from_name - (str) topic author username
  • from_host - (str) topic author origin host
  • hostmask - (str) topic author full usermask: <ident_prefix><from_name>@<from_host>

# channel_topic_is

Answer to a manual user query for a channel's topic. This should be displayed transiently in a dismissable overlay only. Rely on channel_topic to set the channel topic.

Note: Slightly different message keys to channel_topic

  • cid - (int) connection id
  • bid - (int) buffer id
  • chan - (str) channel name
  • text - (str) topic text
  • time - (int UNIX timestamp in seconds) topic set date
  • author - (str) topic author nickname
  • ident_prefix - (str) if the topic author has been ident verified this will be ~ otherwise blank.
  • from_name - (str) topic author username
  • from_host - (str) topic author origin host
  • hostmask - (str) topic author full usermask: <ident_prefix><from_name>@<from_host>

# channel_mode

The mode was changed in this channel. In an initialized channel context, update the mode.

  • cid - (int) connection id
  • bid - (int) buffer id
  • channel - (str) channel name
  • eid - (int) event id
  • from - (str) mode setter nickname (if a user set the mode)
  • server - (str) mode setter server (if the mode was set by the server)
  • diff - (str) mode change diff string, e.g. +nt
  • newmode - (str) full string of new mode without a sign, e.g. nt
  • ops - (obj) see channel_init
  • ident_prefix - (str) if the user has been ident verified this will be ~ otherwise blank. (if mode set by user)
  • from_name - (str) username (if mode set by user)
  • from_host - (str) user origin host (if mode set by user)
  • hostmask - (str) full usermask: <ident_prefix><from_name>@<from_host> (if mode set by user)

# channel_mode_is

A channel's reported mode. In an initialized channel context, update the mode.

Message values same as channel_mode

# user_channel_mode

A users's channel mode was changed. In an initialized channel context, update the user's mode in the memberlist

Message values same as channel_mode with the following additions

  • nick - (str) member's nick
  • target_ident_prefix - (str) if the member has been ident verified this will be ~ otherwise blank.
  • target_name - (str) member's username
  • target_host - (str) member's origin host
  • target_hostmask - (str) member's full usermask: <ident_prefix><from_name>@<from_host>
  • target_account - (str) member account name
  • target_realname - (str) member realname

# member_updates

Map of channel member detail updates retrieved from periodic /who queries. Includes away status, real name, ircserver, usermask, etc. Update each member's details in the member list.

  • cid - (int) connection id
  • bid - (int) buffer id
  • updates - (obj map nick => details obj)
    • nick - (str) member nick
    • realname - (str) member real name
    • ircserver - (str) IRC host from where member is connected to the network
    • hopcount - (int) number of server hops away from the connection user
    • away - (bool) is the member away?
    • ident_prefix, user, userhost, usermask - (str) member usermask details

# self_details

Authenticated user's connection defined details. Includes away status, ircserver, usermask, etc. Log usermask and update connection.

Note: doesn't contain real name, as value can be messed with on some servers.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • server - (str) IRC hostname details queried from. should match ircserver
  • ircserver - IRC hostname from where member is connected to the network
  • away - (bool) is the user away?
  • ident_prefix, user, userhost, usermask - (str) usermask details

# user_away

A channel member is away. In an initialized channel context, mark them as away in the member list. In a conversation context, mark the buffer as away.

  • cid - (int) connection id
  • bid - (int) buffer id
  • nick - (str) member nick
  • msg - (str) away message

# away

A conversation target is away. Mark the buffer as away.

Message values same as user_away

# self_away

The authenticated user went away. Update their away status for the whole connection.

  • cid - (int) connection id
  • bid - (int) buffer id
  • nick - (str) user's nick
  • away_msg - (str) user's away message
  • msg - (str) IRC server notification message, not to be confused with away_msg

# self_back

The authenticated user came back. Update their away status for the whole connection.

  • cid - (int) connection id
  • bid - (int) buffer id
  • nick - (str) user's nick

# joined_channel

Someone joined a channel. In an initialized channel context, add them to the member list. This can be directed at a conversation buffer too.

  • cid - (int) connection id
  • bid - (int) buffer id
  • chan - (str) target buffer name
  • eid - (int) event id
  • nick - (str) member nick
  • ident_prefix - (str) if the member has been ident verified this will be ~ otherwise blank.
  • from_name - (str) member username
  • from_host - (str) member origin host
  • hostmask - (str) full member usermask: <ident_prefix><from_name>@<from_host>

# you_joined_channel

The authenticated user joined a channel. This is for logging purposes only. Rely on channel_init to activate the channel.

Message values same as joined_channel

# parted_channel

Someone left a channel. In an initialized channel context, remove them to the member list. This can be directed at a conversation buffer too.

  • cid - (int) connection id
  • bid - (int) buffer id
  • chan - (str) target buffer name
  • eid - (int) event id
  • nick - (str) member nick
  • msg - (str) part message
  • ident_prefix - (str) if the member has been ident verified this will be ~ otherwise blank.
  • from_name - (str) member username
  • from_host - (str) member origin host
  • hostmask - (str) full member usermask: <ident_prefix><from_name>@<from_name>
  • from_mode - (str) member channel mode before leaving
  • from_account - (str) member account name
  • from_realname - (str) member realname

# you_parted_channel

The authenticated user left a channel. In an initialized channel context, Deactivate the channel

Message values same as parted_channel

# kicked_channel

A channel member was kicked. In an initialized channel context, remove them from the member list. This can be directed at a conversation buffer too.

  • cid - (int) connection id
  • bid - (int) buffer id
  • chan - (str) target buffer name
  • eid - (int) event id
  • kicker - (str) kicker nick
  • msg - (str) kick message
  • nick - (str) kickee nick
  • kicker_ident_prefix - (str) if the kicker has been ident verified this will be ~ otherwise blank.
  • kicker_name - (str) kicker username
  • kicker_host - (str) kicker origin host
  • kicker_hostmask - (str) full kicker usermask: <kicker_ident_prefix><kicker_name>@<kicker_host>
  • kicker_mode - (str) kicker channel mode before leaving
  • kicker_account - (str) kicker account name
  • kicker_realname - (str) kicker realname

# you_kicked_channel

The authenticated user was kicked from a channel. In an initialized channel context, deactivate the channel.

Message values same as kicked_channel

# quit

A channel member quit. In an initialized channel context, remove them from the member list. This can be directed at a conversation buffer too.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • nick - (str) member nickname
  • msg - (str) quit message
  • ident_prefix - (str) if the member has been ident verified this will be ~ otherwise blank.
  • from_name - (str) member username
  • from_host - (str) member origin host
  • hostmask - (str) full member usermask: <ident_prefix><from_name>@<from_name>
  • from_mode - (str) member channel mode before quitting
  • from_account - (str) member account name
  • from_realname - (str) member realname

# quit_server

The authenticated user quit an IRC connection. This is for logging purposes only. Rely on status_changed to deactivate the connection.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • nick - (str) nickname on this connection
  • msg - (str) quit message
  • hostname - (str) connection hostname
  • port - (str) connection port
  • ssl - (bool) is the connection using ssl?

# nickchange

A user changed their nick. In an initialized channel context, update their nick in the member list. In a conversation context, this is for logging purposes only, rely on rename_conversation to change the buffer name.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • newnick - (str) user's new nick
  • oldnick - (str) user's old nick
  • nick - (str) convenience alias for user's old nick

# you_nickchange

The authenticated user changed their nick. Outside of the initial backlog context, update their nick for the whole connection and update their nick in the member list.

Message values same as nickchange

# rename_conversation

A conversation user changed their nick. Update the buffer name.

  • cid - (int) connection id
  • bid - (int) buffer id
  • new_name - (str) new buffer name

# delete_buffer

A buffer was deleted. Remove it from a connection.

  • cid - (int) connection id
  • bid - (int) buffer id

# buffer_archived

A buffer was archived. Update its archived status.

  • cid - (int) connection id
  • bid - (int) buffer id

# buffer_unarchived

A buffer was unarchived. Update its archived status.

  • cid - (int) connection id
  • bid - (int) buffer id

# server_details_changed

A connection's details were edited. Update the connection.

Message values same as makeserver

# whois_response

Details sent in response to a /whois request.

  • cid - (int) connection id
  • bid - (int) buffer id
  • server - (str) IRC hostname whois queried from
  • nick - (str) target nickname
  • stats_dline - (str) conflicted message type. just print the message
  • userip - (str) conflicted message type. just print the message
  • user_logged_in_as - (str) if target is logged in with e.g. nickserv, this is their authenticated nick
  • actual_host - (str) message indicating full target host for a spoofed nick
  • bot_msg - (str) message indicating target is a bot
  • cgi - (str) message indicating target is on a CGI:IRC connection
  • help - (str) message indicating target is available for help
  • host - (str) conflicted message type. just print the message
  • idle_secs - (int) number of seconds target has been idle for
  • signon_time - (int UNIX timestamp in seconds) date since target has been online
  • modes - (str) conflicted message type. just print the message
  • op_nick - (str) nick provided if the target is an oper (should be the same as nick)
  • op_msg - (str) message indicating target is an oper
  • secure - (str) message indicating target is on a secure connection
  • server_nick - (str) nick target it connected as (should be the same as nick)
  • server_addr - (str) IRC hostname target is connected to. update the recipient's hostname (for future whois requests)
  • server_extra - (str) extra information about target IRC hostname
  • user_nick - (str) target nickname (should be the same as nick)
  • user_username - (str) target username. if the target has been ident verified this will be prefixed with ~
  • user_host - (str) target origin hostname
  • user_realname - (str) target real name
  • vworld - (str) conflicted message type. just print the message
  • channels_member - (array) list of channel names (str) target is in
  • channels_owner - (array) list of channels target is owner in (mode q, prefix ~)
  • channels_admin - (array) list of channels target is admin in (mode a, prefix &)
  • channels_op - (array) list of channels target is op in (mode o, prefix @)
  • channels_halfop - (array) list of channels target is half-op in (mode h, prefix %)
  • channels_voiced - (array) list of channels target is voiced in (mode v, prefix +)

# set_ignores

Update the list of ignored user masks.

  • cid - (int) connection id
  • masks - (array) list of usermasks to ignore

# set_shard

Update the session cookie and websocket URL. Use these values for future websocket connections.

  • cookie - (str) new session cookie
  • websocket_host - (str) new websocket URL hostname
  • websocket_path - (str) new websocket URL path

# link_channel

Channel name has been linked to another channel. This message is received when a user is redirected after trying to join a channel alias. Log and make sure anything waiting on the join request to be acknowledged is sorted, if relevant.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • invalid_chan - (str) linked channel alias
  • valid_chan - (str) primary channel name
  • msg - (str) message explaining the redirect

# isupport_params

Useful behavioural metadata about the IRC server for this connection. Store these values per connection for querying later. Do not log.

  • cid - (int) connection id
  • params - (obj) key value metadata mapping
  • usermodes - (str) possible user channel mode values from the PREFIX param, in hierarchical order, e.g. "ohv". Used for prioritising the PREFIX object

The values in the params map vary from server to server, and some are more common than others. Various UI decisions are affected by the values in the params map, some examples

  • CHANTYPES - (str) e.g. '#&' string list of all channel prefixes supported by this server. used for autolinking regex.
  • TOPICLEN - (int) maximum allowed length for topics. used in the topic change prompt
  • NICKLEN - (int) maximum allowed length for nicknames. used in the nick change prompt
  • PREFIX - (obj) e.g. {o: "@", h: "%", v: "+"} matches user channel mode letters to the corresponding prefix, as used in WHOIS, WHO and NAMES output, as well as for display when mode symbols are enabled.

Examples of other ISUPPORT values can be found here:

# myinfo

Various metadata about the IRC server for this connection. Update the connection ircserver value with the server value from this message. Log and store values per connection.

  • cid - (int) connection id
  • bid - (int) buffer id
  • eid - (int) event id
  • server - (str) server hostname
  • version - (str) IRCD software name and version
  • user_modes - (str) available user modes on this server
  • channel_modes - (str) available channel modes on this server
  • rest - (str) available channel modes that take a parameter on this server
Clone this wiki locally