SinusBot Scripting API

ATTENTION: This documentation is outdated. For an up-to-date reference, please go to the bots' webinterface and click Help -> Scripting or continue reading here.

How it works

Basically, the client/bot emits events, that you can capture and react to. Such an event might be a private message, a poke, somebody joining or leaving a channel and so on.

You can take actions on such events, by installing a handler like so:

sinusbot.on('chat', function(ev) {
    // Do something when someone writes to the bot
});

The ev-variable you see as a parameter to our installed handler will be filled with event-specific data. In the chat-example it will contain the following fields:

field value
mode where did the message come from? can be 1 for private, 2 for channel or 3 for server
clientUid the unique identifier of the client
clientId the id of the client (will change after reconnect)
clientNick the nickname of the client that sent the message
clientServerGroups an array of servergroups (if the bot knows about this)
msg the actual message that was sent

So by using a simple command, you can echo back to the client:

sinusbot.on('chat', function(ev) {
    chatPrivate(ev.clientId, 'You just said: ' + ev.msg);
});

It's that simple.

Definitions

Internal URLs

Every resource uploaded to the bot has got its own internal URL that can be used for different calls. Here are some of the available types:

url value
track://uuid this refers to a track/file. The UUID can be obtained through the tag editor
playlist://uuid this refers to a playlist. The UUID can be obtained through the url when browsing that playlist (will find a better way)
res://filename filename refers to a file inside the ./resources/ directory

Channel parameters

Channel parameters are given as an object with the following fields

field value
id (int) id of the channel
name (string)
topic (string)
codec (int) the codecs' id (tbd)
quality (int) (tbd)
maxClients (int) (tbd)
order (int) order-value of the channel (lower = higher)
perm (bool) is permanent?
sperm (bool) is semi-permanent?
default (bool) is the servers' default channel?
enc (bool) is encrypted?

Configuration

Each plugin has its own configuration that will display as a form in the webinterface. An example configuration manifest could look like this:

{
    name: 'Welcome-Sound!',
    version: '1.0',
    description: 'This plugin will let the bot greet everyone.',
    author: 'Michael Friese <[email protected]>',
    vars: {
        message: {
            title: 'The message that should be said. (%n = nickname)',
            type: 'string'
        },
        track: {
            title: 'Track',
            type: 'track',
            placeholder: 'Search for track...'
        }
    }
}

Name, version, author and description are obligatory. The vars object will hold several variables of different types.

Types

type meaning
string will display a simple edit field
multiline will display a multiline input field
track will display a track-search that will result in an object like {"url": "track://", "title": "Blahfoo"} - the url can then be used by the play()-function for example
channel will let the user choose a channel; if the bot is connected by that time, it will show a dropdown list. Result will be the channelId

tbc

Event overview

This is a list of all supported events:

Client-specific events

timer

This event gets emitted every second. You might schedule jobs with this call. (This one is subject to change soon)

The parameter supplied to the handler is the time as unix-timestamp in milliseconds.

connect

Gets called whenever the bot connects to a server

disconnect

Gets called whenever the bot disconnects from a server (or gets disconnected)

chat

Gets called when the bot receives a chat message.

field value
mode where did the message come from? can be 1 for private, 2 for channel or 3 for server
clientUid the unique identifier of the client
clientId the id of the client (will change after reconnect)
clientNick the nickname of the client that sent the message
channel the id of the channel this message was sent to (only if mode == 2)
clientServerGroups an array of servergroups (if the bot knows about this)
msg the actual message that was sent

poke

Gets called when the bot gets poked.

field value
clientUid the unique identifier of the client
clientId the id of the client (will change after reconnect)
clientNick the nickname of the client that sent the message
clientServerGroups an array of servergroups (if the bot knows about this)
msg the actual message that was sent

botMove

Gets called whenever the bot gets moved to a new channel

field value
newChannel id of the new channel
msg an optional message

clientMove

Gets called whenever a client moves to a new channel or becomes visible / invisible to the bot.

field value
newChannel the id of the channel the client moved to (0 if the client went offline)
oldChannel the id of the channel the client moved from (0 if the client just got online)
msg an optional message
clientUid the unique identifier of the client
clientId the id of the client (will change after reconnect)
clientNick the nickname of the client
clientServerGroups an array of servergroups (if the bot knows about this)

clientServergroupAdd

Gets called whenever a client is added to a server group.

field value
serverGroupId the server group that's being used
clientUid the unique identifier of the client that is affected
clientId the id of the client (will change after reconnect)
clientNick the nickname of the client
invokerUid the unique identifier of the client that caused this event
invokerId the id of the client that caused this event (will change after reconnect)
invokerNick the nickname of the client that cause the event

clientServergroupDel

Gets called whenever a client is removed from a server group.

field value
serverGroupId the server group that's being used
clientUid the unique identifier of the client that is affected
clientId the id of the client (will change after reconnect)
clientNick the nickname of the client
invokerUid the unique identifier of the client that caused this event
invokerId the id of the client that caused this event (will change after reconnect)
invokerNick the nickname of the client that cause the event

channelCreate

Gets called whenever a new channel gets created.

channelMove

Gets called whenever a channel moved around.

channelUpdate

Gets called whenever a channel gets updated (codecs, title & such.)

channelDelete

Gets called whenever a channel gets deleted.

record

Gets called whenever someone starts recording.

Bot-specific events

trackEnd

Gets called whenever a track finishes playback.

The parameter supplied will optionally hold a userdefined text given on start of the playback.

track

Gets called whenever a track starts playing

field value
title
artist
album

Commands

Bot-specific commands

log(msg)

Logs a line to the instance log

parameter value
msg (string) the message to log

set(key, object)

Store a value permanently.

get(key)

Return a stored object (returns the object or undefined).

play(url)

Plays a song by its url

parameter value
url (string) this can be a real url for streams or an internal url (see above "Definitions")

Several parameters are available that can be added to the url as query parameters, e.g.

track://uuid?parameter1=paramvalue1&parameter2=paramvalue2
parameter value
ephemeral (bool) if set to true, this will not stop any music already playing but will add this new track on top of the old one. This is mainly used for sound effects
loop (bool) if set to true, the bot will try to gapless playback that track
callback (string) if set, after playback a trackEnd callback will be emitted with this string as parameter

stop()

Stops playing back everything.

next()

Proceeds to the next track (if using a playlist)

prev()

Jumps back to the previous track (if using a playlist)

seek(time)

Seek to the given time in ms.

getTrack()

Returns the currently played track as object. See API for more info.

getPos()

Returns the position of the current track in ms.

say(text[, locale])

Uses TTS to playback the string text as voiceover (TTS needs to be configured); locale is optional

Client-specific commands

setDescription(text)

Sets the client description of the bot (only when online); requires permission to do so.

chatChannel(text)

Writes text to the current channel (requires permission)

chatServer(text)

Writes text to the server (requires permission)

chatPrivate(clientId, text)

Sends text to the client with id clientId

poke(clientId, text)

Pokes the client with id clientId with message text

move(clientId, channelId[, password])

Moves the client with id clientId to channel channelId with optional password password.

kickServer(clientId[, reason])

Kicks the client with id clientId from the server with optional message reason.

kickChannel(clientId[, reason])

Kicks the client with id clientId out of the channel with optional message reason.

getServerUid()

Returns the servers unique identifier (if connected)

running()

Returns true, if the bot is connected

playing()

Returns true, if the bot is playing

getServerName()

Returns the name of the server (if connected)

getServerPlatform()

Returns the servers' platform (if connected)

getServerVersion()

Returns the servers' version (if connected)

getBotId()

Returns the bots' clientId on the server (changes on reconnect)

channelCreate(channelParams)

Creates a channel with parameters of channelParams (see above)

channelUpdate(channelId, channelParams)

Updates a channel

channelMove(channelId[, parentId = 0, order = 0])

Will move a channel to a new parent-Channel and set its order.

channelDelete(channelId[, force=false])

Removes a channel if empty. If force is true, it will be deleted even if it's not empty.