-
Notifications
You must be signed in to change notification settings - Fork 14
API Stream Message 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
- away
- backlog_complete
- backlog_starts
- buffer_archived
- buffer_me_msg
- buffer_msg
- buffer_unarchived
- channel_init
- channel_mode
- channel_mode_is
- channel_timestamp
- channel_topic
- channel_topic_is
- channel_url
- connection_lag
- delete_buffer
- end_of_backlog
- header
- heartbeat_echo
- idle
- isupport_params
- joined_channel
- kicked_channel
- link_channel
- makebuffer
- makeserver
- member_updates
- myinfo
- nickchange
- notice
- num_invites
- oob_include
- oob_skipped
- oob_timeout
- parted_channel
- quit
- quit_server
- rename_conversation
- self_away
- self_away
- self_back
- self_details
- server_details_changed
- set_ignores
- set_shard
- stat_user
- status_changed
- user_away
- user_channel_mode
- whois_response
- you_joined_channel
- you_kicked_channel
- you_nickchange
- you_parted_channel
# 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 ofmakebuffer
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. seestatus_changed
-
fail_info
- (obj) connection failure info. seestatus_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 formusers.<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] seestatus_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 ofdeferred
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 withmode
andparam
values required to build the mode string. this form is also used forchannel_mode
,channel_mode_is
anduser_channel_mode
messages-
add
- (array of obj {"mode":<mode_letter>, "param":<mode_value>}) -
remove
- same asadd
-
-
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 publicpublic
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
queued
connecting
connected
connected_joining
connected_ready
quitting
disconnected
waiting_to_retry
ip_retry
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 thelast_seen_eid
value frommakebuffer
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) seechannel_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 matchircserver
-
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 withaway_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 asnick
) -
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 asnick
) -
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 asnick
) -
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 (modeq
, prefix~
) -
channels_admin
- (array) list of channels target is admin in (modea
, prefix&
) -
channels_op
- (array) list of channels target is op in (modeo
, prefix@
) -
channels_halfop
- (array) list of channels target is half-op in (modeh
, prefix%
) -
channels_voiced
- (array) list of channels target is voiced in (modev
, 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:
- http://www.irc.org/tech_docs/005.html
- http://www.unrealircd.com/files/dev/3.3/tech/RPL_ISUPPORT.html
# 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