Build your own plugins

Server plugins can be developed by anyone, and published by anyone.
You can choose to sell them, or make them free and open source.
They are typically developed in PHP, although some may be developed in NodeJS.
See a current list of the plugins available.

Plugin API


For a sample plugin called 'hide_aargh':


    class plugin_hide_aargh
        public function on_message($message_forum_id, $message, $message_id, $sender_id, $recipient_id, $sender_name, $sender_email, $sender_phone)
            //Do your thing in here. Here is a sample.
            $api = new cls_plugin_api();
            //e.g. hide the message we have just posted if it includes the string 'aargh' in it.
            if(strpos($message, 'aargh') !== false) {
            return true;

Add the entry "hide_aargh" to the "plugins" array in config/config.json to activate the plugin.

More examples

All of the AtomJump-built plugins serve as good example code. But here are some particular cases:
Example 1: A custom button (purple) accessed after tapping a message.
Example 2: A custom button added to the download page, that acts on the whole forum.
For a sample shell project that handles this case, see this project.

Reading Functions


Parameters ($table, $insert_field_names_str,
$insert_field_data_str) Server: >= 0.5.0
  $table                     //AtomJump Loop Server (ssshout by default) database table name eg. "tbl_email"
  $insert_field_names_str    //Insert string e.g. "(var_layers, var_title, var_body, date_when_received, var_whisper)"
  $insert_field_data_str     //Insert values e.g. ('" . clean_data($feed['aj']) . "','". clean_data($subject) . "','" . db_real_escape_string($raw_text) .  "', NOW(), '" . $feed['whisper'] . "') " )    

Parameters ($sql)
Server: >= 0.5.0

An ordinary SELECT SQL query.


Parameters ($table, $update_set)
Server: >= 0.5.0

Update_set is the SQL after an 'UPDATE table SET' e.g. "var_title = 'test' WHERE var_title = 'test2'" - can have multiple fields.

Parameters ($results)
Server: >= 0.5.21

Get an array of rows from a database query.


Parameters ($string)
Server: >= 0.5.21

Ensure the string is escaped for input into the database.


No parameters
Server: >= 0.5.21

Returns the database error text.


No parameters
Server: >= 0.5.21

Get the last database inserted id field value.


Parameters ($message_forum_name)
Server: >= 0.5.0
Output is an array:
[ forum_id, access_type, forum_group_user_id, requires_password ]

Where 'forum_id' e.g. 34
	  'access_type' eg. "readwrite", "read"
	  'forum_owner_user_id' is the user id to send a message to, to become visible to all the private forum owners.
          'requires_password' is 'true' if the forum is password protected, or 'false' if not. (Server >= 2.3.4)


No parameters
Server: > 0.5.0

Get the user's ip address, although this is now an artificial ip address, actually a unique 'ip' based off their user id.


No parameters
Server: >= 0.5.0

Returns the integer user id value of the current user.


Required Parameters ($check_forum_id)
Server: >= 2.3.4

Check if a layer (numerical ID) has been granted access (i.e. the password has been specifically entered by the current user). If there is no need for access to be granted (i.e. on a public forum - see get_forum_id() and 'requires_password' return param) you should ignore any 'false' values.

Returns: true/false



Output parameters ($message_forum_id, $message, $message_id, $sender_id, $recipient_id, $sender_name,
$sender_email, $sender_phone, $message_forum_name)
Plugin function returns
Server: >= 0.5.1 ($message_forum_name >= 0.7.6)

Occurs after a message being posted.


Output parameters ($message)
Plugin function returns
Server: >= 0.5.0

Occurs just before a message is posted, allowing changes to the message text.

Output parameters ($message)
 Plugin function writes HTML inside ordinary PHP tags e.g.

?>Your settings HTML<?php 
Server: >= 0.5.9


Output parameters ($user_id, $full_request: array of options, $type: NEW or SAVE) Plugin function returns (true/false)

Called when the settings are saved. $user_id is the integer user's id being saved. $full_request is the $_REQUEST array with the user's entered values. $type can be 'NEW' if it is a new record, or 'SAVE' to save an existing record.


Output parameters ($message)
Plugin function writes HTML inside ordinary PHP tags e.g.
?>Your settings HTML<?php 
Server: >= 0.5.9


Output parameters ($message_id)
Plugin function should return ($html)

When a particular message is clicked, a screen with more options (e.g. deleting the message) appears. This plugin function should return the HTML for the new custom button directly, including a javascript onclick="" event, and code, such as a server 'get' request to handle that event.

Server: >= 2.2.8


Output parameters ($stage, $message, $message_details, $message_id, $sender_id, $recipient_id, $in_data)
Plugin function should return ($ret, $ret_data) where $ret is true, unless a recipient is not to get a message, when your plugin function should return $ret = false
$ret_data should be used to forward the data on to the next stage function, in the $in_data parameter.

Server: >= 0.7.7

This hook allows you to embed custom code into a notification e.g. the plugin 'notifications' uses this function to send messages to the AtomJump phone app.

Used at 3 stages of the notification process, defined by $stage. Stages are:

1. init          - this call occurs once the first notification in a group is reached
2. addrecipient  - this occurs for each recipient in the group
3. send			 - this occurs on being ready to send 

$message_details will be an array in the following format:

array("observe_message" => $observe_message,		//This is the message to be written next to the visual link to the forum
		 "observe_url" => $observe_url,             //This is the URL of the visual link to the forum
		 "forum_message" => $layer_message,			//A message that preceeds the name of the forum the message was sent from
		 "forum_name" => $layer_name,				//The name of the forum the message was sent from
		 "remove_message" => $remove_message,		//A description of what to do to remove the message
		 "remove_url" => $remove_url);              //The URL to remove the message

Writing Functions

Required Parameters ($sender_name_str, $message, $recipient_ip_colon_id, $sender_email, $sender_ip, $message_forum_id, $options)
Server: >= 0.5.0

Optional Parameters in an $options object: ($sender_still_typing, $known_message_id, $sender_phone, $javascript_client_msg_id, $forum_owner_id, $social_post_short_code, $social_recipient_handle_str, $date_override, $latitude, $longitude, $login_as, $allow_plugins, $allowed_plugins, $notification, $always_send_email)
Server: >= 0.5.0

Additions: ($login_as), server >= 0.5.1
($allow_plugins, $allowed_plugins), server >= 0.5.5 ($notification, $always_send_email), server >= 1.0.4

Output parameters ($message_id)
	$sender_name_str,                           //e.g. 'Fred'
	$message,                                   //Message being sent e.g "Hello world!"
	$recipient_id,                              //User id of recipient e.g. "" 
	$sender_email,                              //Sender's email address e.g. ""
	$sender_ip,                                 //Sender's ip address eg. ""
	$message_forum_id,                          //Forum id e.g. 23, which is derived from a forum name e.g. 'aj_test'


	$sender_still_typing = false;               //Set to true if this is a partially completed message
	$known_message_id = null;                   //If received an id from this function in the past
	$sender_phone = null;                       //Include the phone number for configuration purposes
	$javascript_client_msg_id = null;           //Browser id for this message.
	$forum_owner_id = null;                     //User id of forum owner
	$social_post_short_code = null;             //eg 'twt' for twitter, 'fcb' for facebook
	$social_recipient_handle_str = null;        //eg. 'atomjump' for '@atomjump' on Twitter
	$date_override = null;                      //optional string for a custom date (as opposed to now) 
	$latitude = 0.0;                            //for potential future location expansion
	$longitude = 0.0;                            //for potential future location expansion
	$login_as = false;                          //Also login as this user
	$allow_plugins = false;                     //To prevent infinite message sending loops, we don't refer to any other plugins
												//after a message send
	$allowed_plugins = null;                    //Use the standard plugins (null), or an array of approved plugins from the plugin
												//developer. However, plugins that work with before_msg will continue to work 
	$notification = true;						//Set to false to switch off notifications from this message
	$always_send_email = false;					//Set to true to ensure an email will always be sent to the recipient(s). Usually, messages within around 20 minutes won't multiple-email the user (when false).

Usage example:

    $options = array('notification' => false);		//turn off any notifications from these messages
    $new_message_id = $api->new_message($helper, $new_message, $sender_ip . ":" . $sender_id, $helper_email, $sender_ip, $message_forum_id, $options);

Warning: if your plugin is a standalone script (as opposed to being called from the main server), you will need to also call


if you want the notifications to be sent, as these happen in parallel.


Required Parameters ($message_id)
Server: >= 0.5.0

Optional Parameters ($warn_admin)
Server: >= 0.5.0

Hides a message from view, where $message_id is an integer. $warn_admin can be true/false to warn the owner of the forum of the message being hidden.
Sending Emails

Although this is not yet a part of the plugin API, you can include the config/db_config.php file in your own script and use either the cc_mail_direct() or cc_mail() functions. The direct() version will immediately send an email (with an execution pause of a few seconds), while the regular version will log the request in parallel. You should set a global variable $notify beforehand
$notify = true;
See the 'Notifications' plugin at, script register.php for an example. If you use the regular cc_mail() version, you will need to also call
if you want the notifications to be sent, at the end of the script.



Required Parameters ($command)
Server: >= 0.5.5
Optional Parameters ($platform:'linux'/'windows' default:'linux')
Run a unix shell command in a parallel process. This allows e.g. a process to run in the background and after a period of time do some action. Also see complete_parallel_calls().


No parameters.
Server: >= 0.9.0

This should be called at the end of your script to complete all of the parallel_system_call() commands, if your script is a standalone script (i.e. not called via a hook). It will hard exit the script after completion, and close down the sessions.


Required parameters ($number, $lang)
Server: >= 2.6.7

Input, ideally an integer between 0 - 60 (60 seconds in a minute means this is usually the largest number we need for most things, i.e. 59 seconds ago), and a language e.g. "en", "ch" from the messages.json translation list. However, any number can be used and the default is to return the English number if there is no matching number in the messages array "number" conversion for the input language.

Global Variables


The AtomJump Messaging Server's URL. Make the variable available to your function with:
global $root_server_url;

The global configuration file as an array. This can be accessed with e.g. $cnf['webRoot']. Make the variable available to your function with:
global $cnf;

The global messages configuration file as an array. This can be accessed with e.g. $msg['msgs'][$lang]['description']. Make the variable available to your function with:
global $msg;

The current selected language e.g. "en" for English. Make the variable available to your function with:
global $lang;

The current selected database configuration. This can be accessed with e.g. $db_cnf['user']. Make the variable available to your function with:
global $db_cnf;

Allow email notifications to be sent if 'true'. You should set this within your own script. Please see the section 'Writing Functions > Sending Emails'.

$_REQUEST['uniqueFeedbackId'] / $_REQUEST['passcode']

Either of these can be the current forum's name as a string. You should check for both.


Set on sign in. This is the email of the signed in user.


This username is used potentially before another name is set e.g. 'Anon 55'.


The current user has the authority to read and write to this layer ID (applies to any forum, not just password protected forums).