JSON-RPC:User

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

IMPORTANT: many  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  and.

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

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

The detail level depends on the API call: The detail level can be overridden by use of, see the documentation of the API calls.
 * has a default level of 2
 * has a default level of 4

= 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: Optional:
 * nick: the nick name or the UID
 * newnick: the new nick name
 * 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 name / ident

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: Optional:
 * nick: the nick name or the UID
 * modes: the mode string, eg
 * 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: Optional:
 * nick: the nick name or the UID
 * snomask: the snomask string, eg
 * 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: Optional:
 * 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
 * class: the class to put the user in. If this option is not specified then  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: . 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: . 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: Optional arguments:
 * nick: the nick name or the UID
 * channel: the channel(s) to join (e.g.  or  )
 * 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  on IRC). If force is not set, or set to false, then it will be a regular  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: Optional arguments:
 * nick: the nick name or the UID
 * channel: the channel(s) to part (e.g.  or  )
 * 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  will show that the user is forcefully killed, while   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  will show that the user is forcefully killed, while   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}

= See also =
 * For kicking a user from a channel, see the channel.kick API call