IRCCD-API(7) Miscellaneous Information Manual IRCCD-API(7)

irccd-api
irccd network protocol

This guide will help you controlling irccd via sockets.

For this to work, you need to define at least one transport in your irccd.conf file, for more information see irccd.conf(5).

Most of the commands are similar to irccdctl and mapped to the same network command. For more detailed information about each command, take a look at irccdctl(1) before.

Irccd use JSON as protocol for sending and receiving data. A message must ends with \r\n\r\n to be complete, thus it's possible to write JSON messages in multiple lines.

For example, this buffer will be parsed as two different messages.

{
  "param1": "value1"
}

{
  "param1": "value1"
}

Warning: please note that the \r\n\r\n characters are the escape characters of line feed and new line, not the concatenation of \ and r.

All commands emit a response with the following properties:
command (string)
the result of the issued command.
error (int)
the error error code, not defined on success.
errorCategory (string)
the error category (example: server, plugin).
errorMessage (string)
the arbitrary error message.

Example with a successful message:

{
  "command": "server-message",
}

Example with an error:

{
  "command": "server-message",
  "error": 1,
  "errorCagegory": "server",
  "errorMessage": "server not found"
}

The following commands are available.
Set or get values to a plugin.

Available properties:

command (string)
must be plugin-config.
plugin (string)
plugin identifier.
variable (string)
the variable (Optional, default: undefined).
value (string)
the value (Optional, default: undefined)

The following properties are available in a successful response when getting a value:

variables (list)
All values or unique variable.
Retrieve plugin information.

Available properties:

command (string)
must be plugin-info.
plugin (string)
plugin identifier.

The following properties are available in a successful response:

author (string)
author name.
license (string)
plugin license.
summary (string)
plugin description.
version (string)
arbitrary version.
Get the list of all loaded plugins.

Available properties:

command (string)
must be plugin-list.

The following properties are available in a successful response:

list (list)
a list of plugin names.
Load a plugin by searching it.

Available properties:

command (string)
must be plugin-load.
plugin (identifier)
the plugin identifier.
Reload a plugin.

Available properties:

command (string)
must be plugin-reload.
plugin (identifier)
the plugin identifier.
Unload a plugin.

Available properties:

command (string)
must be plugin-unload.
plugin (identifier)
the plugin identifier.
Add a new rule.

Available properties:

command (string)
must be rule-add.
channels (list)
a list of channels to match (Optional, default: undefined).
events (list)
a list of events to match (Optional, default: undefined).
origins (list)
a list of origins to match (Optional, default: undefined).
plugins (list)
a list of plugins to match (Optional, default: undefined).
servers (list)
a list of servers to match (Optional, default: undefined).
action (string)
must be accept or drop.
index (unsigned)
rule index (Optional, default: undefined).
Edit a rule in place.

Available properties:

command (string)
must be rule-edit.
add-channels (list)
a list of channels to match (Optional, default: undefined).
add-events (list)
a list of events to match (Optional, default: undefined).
add-origins (list)
a list of origins to match (Optional, default: undefined).
add-plugins (list)
a list of plugins to match (Optional, default: undefined).
add-servers (list)
a list of servers to match (Optional, default: undefined).
remove-channels (list)
a list of channels to unmatch (Optional, default: undefined).
remove-events (list)
a list of events to unmatch (Optional, default: undefined).
remove-origins (list)
a list of origins to unmatch (Optional, default: undefined).
remove-plugins (list)
a list of plugins to unmatch (Optional, default: undefined).
remove-servers (list)
a list of servers to unmatch (Optional, default: undefined).
action (string)
can be accept or drop (Optional, default: undefined).
index (unsigned)
rule index.
Show information about a rule.

Available properties:

command (string)
must be rule-info.
index (unsigned)
rule index.

The following properties are available in a successful response:

servers (list)
a list of servers matched.
channels (list)
a list of channels matched.
origins (list)
a list of origins matched.
plugins (list)
a list of plugins matched.
events (list)
a list of events matched.
action (string)
rule action, accept or drop.
Get a list of rules.

Available properties:

command (string)
must be rule-list.

The following properties are available in a successful response:

list (list)
a list of object that contain the same information as rule-info command was invoked.
Move a rule.

Available properties:

command (string)
must be rule-move.
from (int)
the source index.
to (int)
the destination index.
Remove a rule.

Available properties:

command (string)
must be rule-remove.
index (int)
rule index.
Connect to a server.

Available properties:

command (string)
must be server-connect.
name (string)
the server unique id.
hostname (string)
the host address.
port (int)
the port number (Optional, default: 6667).
ssl (bool)
use SSL (Optional, default: false).
nickname (string)
the nickname to use (Optional, default: irccd).
username (string)
the user name to use (Optional, default: irccd).
realname (string)
the real name to use. (Optional, default: IRC Client Daemon).
ctcpVersion (string)
the CTCP Version to answer. (Optional, default: the irccd's version),
commandChar (string)
the command character to use to invoke command. (Optional, default: !).
Disconnect from a server.

If server is not specified, irccd disconnects all servers.

Available properties:

command (string)
must be server-disconnect.
server (string)
the server unique id (Optional, default: none).
Get server information.

Available properties:

command (string)
must be server-info.
server (string)
the server unique id.

The following properties are available in a successful response:

name (string)
the server unique id.
hostname (string)
the server hostname.
port (int)
the port.
ipv4 (bool)
true if using IPv6.
ipv6 (bool)
true if using IPv6.
ssl (bool)
true if connection is using SSL.
channels (list)
list of channels.
nickname (string)
the current nickname in use.
username (string)
the username in use.
realname (string)
the realname in use.
Invite the specified target on the channel.

Available properties:

command (string)
must be server-invite.
server (string)
the server unique id.
target (string)
the nickname to invite.
channel (string)
the channel.
Join the specified channel.

Available properties:

command (string)
must be server-join.
server (string)
the server unique id.
channel (string)
the channel to join.
password (string)
the password (Optional, default: none).
Kick the specified target from the channel.

Available properties:

command (string)
must be server-kick.
server (string)
the server unique id.
target (string)
the target nickname.
channel (string)
the channel.
reason (string)
the reason (Optional, default: none).
Get the list of all connected servers.

Available properties:

command (string)
must be server-list.

The following properties are available in a successful response:

list (list)
the list of all server unique ids as integers.
Send an action emote.

Available properties:

command (string)
must be server-me.
server (string)
the server unique id.
target (string)
the target or channel.
message (string)
the message.
Send a message to the specified target or channel.

Available properties:

command (string)
must be server-message.
server (string)
the server unique id.
target (string)
the target or channel.
message (string)
the message.
Change channel or bot mode.

Available properties:

command (string)
must be server-mode.
server (string)
the server unique id.
channel (string)
the channel or irccd's nickname
mode (string)
the mode.
limit (string)
a optional limit.
user (string)
a optional user.
mask (string)
a optional mask.
Change irccd's nickname.

Available properties:

command (string)
must be server-nick.
server (string)
the server unique id.
nickname (string)
the new nickname.
Send a private notice to the specified target.

Available properties:

command (string)
must be server-notice.
server (string)
the server unique id.
target (string)
the target.
message (string)
the notice message.
Leave the specified channel.

Available properties:

command (string)
must be server-part.
server (string)
the unique server id.
channel (string)
the channel to leave.
reason (string)
the reason (Optional, default: none).
Force reconnection of one or all servers.

If server is not specified, all servers will try to reconnect.

Available properties:

command (string)
must be server-reconnect.
server (string)
the server unique id (Optional, default: none).
Change the topic of the specified channel.

Available properties:

command (string)
must be server-topic.
server (string)
the unique server id.
channel (string)
the channel.
topic (string)
the new topic.

irccd(1)
October 6, 2019 Linux 5.3.1-arch1-1-ARCH