JSON Methods

rpc: set_issuer, info, add_timer, del_timer
stats: get
log: send, list, subscribe, unsubscribe
user: list, get, set_nick, set_username, set_realname, set_vhost, set_mode, set_snomask, set_oper
whowas: get
server: list, get, rehash, connect, disconnect
channel: list, get, set_mode, set_topic, kick
server_ban: list, get, add, del
server_ban_exception: list, get, add, del
spamfilter: list, get, add, del
name_ban: list, get, add, del

JSON Basics

JSON-RPC Technical documentation

The user.* JSON RPC calls can list and retrieve information about users.

IMPORTANT: many user.set_* calls require all servers on the network to be using UnrealIRCd 6.0.6 or later, otherwise the commands don't work or you get desynchs. Also, set::limit-svscmds should be set to servers (which is the default). The same is (partially) true for user.join and user.part.

Structure of a client object

A "Client object" is used in responses. In case of user.* API calls the result in response will always be a user (never a server).

This can be a user, a server or a freshly accepted connection that is still in the handshake and we don't know yet what it will be.

Detail level	Variable	Description	Example value
0+	name	The name of the client (nick name, server name, ..)	`Syzop`
0+	id	The unique client ID	`001F9RV02`
1+	hostname	Resolved hostname (or IP)	`xyz.example.org`
1+	ip	IP address of the user (empty for services)	`198.51.100.1`
1+	details	Detailed description of the client. The output depends on the type of client and what information we have.	`nick!user@host` `[email protected]` `[198.51.100.1]`
1+	geoip	GeoIP information regarding the IP address of the user (not always available)	(see next)
1+	geoip.country_code	The ISO 3166-1 alpha-2 country code	`NL`
1+	geoip.asn	The AS (Autonomous System) number that the user is connecting from	`16276`
1+	geoip.asname	The AS (Autonomous System) name that the user is connecting from	`OVH SAS`
2+	server_port	Server TCP port (unrealircd side)	`6697`
2+	client_port	Client TCP port (client side)	`37030`
2+	connected_since	Date/time when the client connected (only available for local clients)	`2022-05-23T11:02:06.000Z`
2+	idle_since	Last time the client said anything in PM or channel (only available for local clients)	`2022-05-23T11:02:06.000Z`
2+	tls	If the client is using SSL/TLS then this contains a tls object which has two members	(see next)
2+	tls.cipher	The TLS cipher negotiated with the client	`TLSv1.3-TLS_CHACHA20_POLY1305_SHA256`
2+	tls.certfp	The client Certificate fingerprint (if any)	`aafe66a7d808e1fca077805c54b1274a92d30c3023e35ec130f358d238218296`
2+	user	If the client is a user (a person) then additional information is available in this object.	See client.user object
2+	server	If the client is a server then additional information is available in this object.	See client.server object

See also below for the user and server objects.

client.user object

If the client is a user then there is a user object within the client object:

Detail level	Variable	Description	Example value
2+	user.username	The user name / ident	`~xyz`
2+	user.realname	The real name / GECOS	`IRC User`
2+	user.vhost	If the user is `+x` or `+t` this contains the vhost/cloakedhost	`oper/netadmin.test.net`
2+	user.cloakedhost	The calculated cloaked host, even if the user is not `+x`	`Mask-8608861.example.net`
2+	user.servername	The server to which the user is connected	`irc.example.net`
2+	user.account	The account name, if the user is logged in to Services.	`SomeAccount`
2+	user.reputation	The reputation score.	`10000`
2+	user.security-groups	The security groups that the user is in.	`["known-users"]`
2+	user.modes	The user modes of the user.	`"iwx"`
2+	user.snomasks	The snomasks of the user, if they are IRCOp.	`"iwx"`
2+	user.operlogin	The name of the oper { } block, if they are IRCOp.	`"iwx"`
2+	user.snomasks	The oper::operclass, if they are IRCOp.	`"iwx"`
3	user.channels	The channels the user is in. Minimized and capped at 384 bytes total length.	`["#a","#b","#c"]`
4	user.channels	The channels the user is in with the level	`[{"name": "#a", "level": "o"}, {"name": "#b", "level": "o"}, {"name": "#c", "level": "o"}]`

client.server object

If the client is a server then there is a server object within the client object:

Detail level	Description	Example value
2+	server.info	The server description	`Primary IRC server of example.net`
2+	server.num_users	Number of currently connected users	`123`
2+	server.boot_time	Date/time the server was started	`2022-05-23T11:02:06.000Z`
2+	server.synced	Set to 1 if the server is synced, 0 if the server is currently linking in and syncing users/channels/etc.	`1`
2+	server.features.software	Server software version in use	`UnrealIRCd 6.0.0`
2+	server.features.protocol	UnrealIRCd protocol version	`6000`
2+	server.features.usermodes	User modes supported by this server	`abcd`
2+	server.features.chanmodes	Channel modes supported by this server. This is an array of 4 strings, the same format as IRC numeric 005 CHANMODES=.	`['abc','def','ghi','jkl']`
2+	server.features.nick_character_sets	Nick Character Sets supported by this server. Comma separated string.

NOTE: The client.server object is never returned with the user.* API calls, because the user.* API calls only deal with users. In the future there will be server.* API calls for handling servers.

The detail level depends on the API call:

user.list has a default level of 2
user.get has a default level of 4

The detail level can be overridden by use of object_detail_level, see the documentation of the API calls.

API Calls

user.list

List users.

Request arguments

There are no mandatory arguments.

Optional arguments:

object_detail_level: set the detail of the response object, see the Detail level column in Structure of a client object. In this RPC call it defaults to 2 if this parameter is not specified.

Example

{"jsonrpc": "2.0", "method": "user.list", "params": {}, "id": 123}

user.get

Retrieve all details of a single user.

Request arguments

Mandatory argument:

nick: the nick name or the UID

Optional arguments:

object_detail_level: set the detail of the response object, see the Detail level column in Structure of a client object. In this RPC call it defaults to 4 if this parameter is not specified.

Example

Simply by nick name:

{"jsonrpc": "2.0", "method": "user.get", "params": {"nick":"XYZ"}, "id": 123}

Or by NICK ID, which is safer if you already know the ID, because the ID will not change between nick changes:

{"jsonrpc": "2.0", "method": "user.get", "params": {"nick":"0017A04PU"}, "id": 123}

user.set_nick

Sets the nick name of a user (changes the nick).

Request arguments

Mandatory arguments:

nick: the nick name or the UID
newnick: the new nick name

Optional:

force: if set to true then q-lines (banned nick) checks will be bypassed. And also, if the new nick name already exists, the other existing user is killed and we will take that new nick.

Example

{"jsonrpc": "2.0", "method": "user.set_nick", "params": {"nick":"XYZ","newnick":"some_new_nick"}, "id": 123}

user.set_username

Set the username / ident of a user.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
username: the new user name / ident

Example

{"jsonrpc": "2.0", "method": "user.set_username", "params": {"nick":"XYZ","username":"someident"}, "id": 123}

user.set_realname

Set the realname / gecos of a user.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
realname: the new user realname

Example

{"jsonrpc": "2.0", "method": "user.set_username", "params": {"nick":"XYZ","realname":"I like apples"}, "id": 123}

user.set_vhost

Set a virtual host (vhost) on the user.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
vhost: the new virtual host

Example

{"jsonrpc": "2.0", "method": "user.set_vhost", "params": {"nick":"XYZ","vhost":"likes.apples"}, "id": 123}

user.set_mode

Change the modes of a user.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
modes: the mode string, eg -i+w

Optional:

hidden: if this is set to true then don't show the mode change to the user (generally not recommended)

NOTE: For changing snomask you need to use the user.set_snomask API call!

Example

{"jsonrpc": "2.0", "method": "user.set_mode", "params": {"nick":"XYZ","modes":"-i+w"}, "id": 123}

user.set_snomask

Change the snomask of a user.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
snomask: the snomask string, eg -j+R

Optional:

hidden: if this is set to true then don't show the snomask change to the user (generally not recommended)

Example

{"jsonrpc": "2.0", "method": "user.set_mode", "params": {"nick":"XYZ","snomask":"-j+R"}, "id": 123}

user.set_oper

Make user an IRC operator.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
oper_account: the oper account, to be shown in WHOIS to fellow ircops and in logs.
oper_class: the operclass. Usually one of the default operclasses like netadmin-with-override

Optional:

class: the class to put the user in. If this option is not specified then opers is assumed, since this class exists in most unrealircd.conf's. You can specify "" (empty) if you don't want to put the user in a class.
modes: user modes to set on oper. For example: +xws. If this option is not specified then set::modes-on-oper is used. You can specify "" (empty) if you don't want to set any additional modes on the user.
snomask: snomask to set on oper. For example: +bBcdfkqsSoO. If this option is not specified then set::snomask-on-oper is used. You can specify "" (empty) if you don't want to set any snomasks on the user.
vhost: virtual host to set on oper.

Example

{"jsonrpc": "2.0", "method": "user.set_oper", "params": {"nick":"XYZ","oper_account":"SomeOper","oper_class":"netadmin-with-override","class":"opers","modes":"+ws","snomask":"+bBcdfkqsSoO","vhost":"oper.on.this.net"}, "id": 123}

user.join

Join a user to a channel.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
channel: the channel(s) to join (e.g. #channel or #channel1,#channel2)

Optional arguments:

key: the key of the channel(s) (only for channels with +k needed, again separate by colon for multiple channels)
force: whether to bypass join restrictions or not

NOTE: If force is set to true then the user will walk through bans, modes and other restrictions (similar to SAJOIN on IRC). If force is not set, or set to false, then it will be a regular JOIN attempt that may fail. If it fails then the user will see an error message on their screen, such as for example Cannot join channel (+k).

Result

This API call will always return boolean true. For technical reasons it is hard for us to check if the join actually succeeded (the join could be done on a remote server, asynchronously, seconds after we return)

Example

Normal join without bypassing any restrictions:

{"jsonrpc": "2.0", "method": "user.join", "params": {"nick":"XYZ","channel":"#main"}, "id": 123}

Joining through all restrictions, similar to a SAJOIN:

{"jsonrpc": "2.0", "method": "user.join", "params": {"nick":"XYZ","channel":"#restricted","force":true}, "id": 123}

user.part

Part a user from a channel.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
channel: the channel(s) to part (e.g. #channel or #channel1,#channel2)

Optional arguments:

force: show force notification

NOTE: If force is set to true then the user will see a notice that they were forcefully PARTed from the channel(s). If force is not set, or set to false, then there will be no such notice.

Result

This API call will always return boolean true.

Example

{"jsonrpc": "2.0", "method": "user.part", "params": {"nick":"XYZ","channel":"#main"}, "id": 123}

user.kill

Kill a user, showing that the user was forcefully removed.

NOTE: There is also user.quit. The difference is that user.kill will show that the user is forcefully killed, while user.quit pretend the user quit normally. This slight difference may invoke certain client behavior. For example, some clients don't immediately reconnect for a KILL but do so on a QUIT.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
reason: reason for the kill

Example

{"jsonrpc": "2.0", "method": "user.kill", "params": {"nick":"XYZ","reason":"go away"}, "id": 123}

user.quit

Quit a user, pretending it was a normal QUIT.

NOTE: There is also user.kill. The difference is that user.kill will show that the user is forcefully killed, while user.quit pretend the user quit normally. This slight difference may invoke certain client behavior. For example, some clients don't immediately reconnect for a KILL but do so on a QUIT.

Request arguments

Mandatory arguments:

nick: the nick name or the UID
reason: reason for the quit

Example

{"jsonrpc": "2.0", "method": "user.quit", "params": {"nick":"XYZ","reason":"go away"}, "id": 123}

JSON-RPC:User

Structure of a client object

client.user object

client.server object

API Calls

user.list

Request arguments

Example

user.get

Request arguments

Example

user.set_nick

Request arguments

Example

user.set_username

Request arguments

Example

user.set_realname

Request arguments

Example

user.set_vhost

Request arguments

Example

user.set_mode

Request arguments

Example

user.set_snomask

Request arguments

Example

user.set_oper

Request arguments

Example

user.join

Request arguments

Result

Example

user.part

Request arguments

Result

Example

user.kill

Request arguments

Example

user.quit

Request arguments

Example

See also

Navigation menu

Search