Tip of the day: If you want to bypass access checks for channels as an IRCOp, use SAMODE or SAJOIN. Or use OperOverride.

JSON-RPC:Channel

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

The channel.* JSON RPC calls can list and retrieve information about channels.

Structure of a channel

A "Channel object" is used in responses.

Detail level Variable Description Example value
0+ name The name of the channel #five
1+ creation_time Date/time the channel was first created 2022-05-23T11:02:13.000Z
1+ num_users Number of users in the channel 1
1+ topic Topic of the channel (if a topic is set) Welcome everyone
1+ topic_set_by Name of the user who set the topic (if a topic is set) Syzop
1+ topic_set_at Date/time when the topic was set (if a topic is set) 2022-05-23T1:30:00.000Z
1+ modes Channel modes that are set (not including list modes) ntf [4j#R1,5m#M1,3n#N1,3t#b1]:2
2+ bans List of all bans (+b) in the channel [{"name": "some!nice@ban","set_by": "some_user","set_at": "2023-01-04T07:52:54.000Z"}]
2+ ban_exemptions List of all ban exceptions (+e) in the channel [{"name": "some!nice@exempt","set_by": "some_user","set_at": "2023-01-04T07:52:54.000Z"}]
2+ invite_exceptions List of all invite exceptions (+I) in the channel [{"name": "some!nice@invex","set_by": "some_user","set_at": "2023-01-04T07:52:54.000Z"}]
3 members List of members (nicks) that are in the channel - simple [{"level": "o", "name": "one", "id": "001QMQ00B"}, {"name": "two", "id": "001TKVY0A"}]
4 members List of members (nicks) that are in the channel - more details [{"level": "o", "name": "one", "id": "001QMQ00B", "hostname": "localhost", "ip": "127.0.0.1", "details": "one!test@localhost"}, {"name": "two", "id": "001TKVY0A", "hostname": "localhost", "ip": "127.0.0.1", "details": "two!~x@localhost"}]
5 members List of members (nicks) that are in the channel - almost completely expanded. Only the members.user.channels object is NOT added. That field would otherwise show all the channels the user is in, which is generally not useful if you are using channel.* API calls. Too big to show here
6 members Don't use this level, it's for JSON logging only. Don't use this level
7 members List of members (nicks) that are in the channel - completely expanded, not recommended. Too big to show here

The detail level depends on the API call:

  • channel.list has a default level of 1
  • channel.get has a default level of 3

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

API Calls

channel.list

List channels.

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 channel. In this RPC call it defaults to 1 if this parameter is not specified.

Example

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

channel.get

Retrieve all details of a single channel. This returns more information than a channel.list call, see the end of Structure of a channel.

Request arguments

Mandatory argument:

  • channel: the name of the channel

Optional arguments:

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

Example

{"jsonrpc": "2.0", "method": "channel.get", "params": {"channel":"#test"}, "id": 123}

channel.set_mode

Set and unset modes on a channel.

Request arguments

Mandatory argument:

  • channel: the name of the channel
  • modes: the mode(s) to change, eg +be
  • parameters: the parameters, eg some!nice@ban some!nice@invex

Example

{"jsonrpc": "2.0", "method": "channel.set_mode", "params": {"channel":"#test","modes":"be","parameters":"some!nice@ban some!nice@invex"}, "id": 123}

channel.set_topic

Set a topic on a channel.

Request arguments

Mandatory argument:

  • channel: the name of the channel
  • topic: the new topic

Optional arguments:

  • set_by: who set the topic (but, see important note below)
  • set_at: when the topic was set (timestamp)

NOTE: The TOPIC set message will always be shown as coming from the server, so set_by will not spoof it as coming from a certain nick name. The set_by/set_at is used for displaying who set the topic and when if you query by TOPIC #channel

Example

{"jsonrpc": "2.0", "method": "channel.set_topic", "params": {"channel":"#test","topic":"This is a nice new topic","set_by":"SomeUser","set_at","2023-01-07T09:19:59.000Z"}, "id": 123}

channel.kick

Kick a user from a channel

Request arguments

Mandatory argument:

  • channel: the name of the channel
  • nick: the user to kick
  • reason: the kick reason (shown in the channel)

Example

{"jsonrpc": "2.0", "method": "channel.kick", "params": {"channel":"#test","nick":"XYZ","reason":"go away plz"}, "id": 123}

See also

  • For joining a user to a channel, see the user.join API call
  • For parting a user from a channel, see the user.part API call