SmartBots PHP API Brought to you by RenderWorks

Getting Started

This API kit has been created from scratch to ease development of your online web services which integrate with SmartBots.

To get started with this API, you will first need to know the basics of PHP programming. This web documentation uses some terms which are specific to Object Orientated PHP programming, so it may be best to freshen yourself up on the terminology here before continuing. Please do not contact us if you do not know any programming language, as we will not be able to teach you it.

Download at GitHub

To begin, you will first need to create a blank .php file and include the 'smartbots_api.php' file.

<?php
	include("smartbots_api.php"); // Include the SmartBots API file.

Next, we will need to define your SmartBots Developer API key, your bot's name and access code so that it's easier to use them later.

$apiKey        = "e40e365171a99nl05bdmd697273b573t"; // SmartBots API Key.
$botName       = "Example Resident"; // The bot's full name.
$botAccessCode = "KbYpnfa"; // The bot's access code.

If you're not familiar with Object-Orientated PHP, the next section may look a little strange, however follow the instructions and all should be clear.

Now we will create the $bot variable and instansiate a new SmartBot() class so that we can begin making our bot function.

$bot = new SmartBot(); // Instansiate a new SmartBot class.

To let the SmartBots API know what bot we are going to be controlling, we now need to use the setup() method/function to enter in the variables we created earlier. The setup process returns TRUE or FALSE, depending on whether or not it was successful, meaning that you would use it within an 'if' statement if you wanted.

$bot->setup($apiKey, $botName, $botAccessCode); // Pass the setup variables to the API.

Your SmartBot is now connected to the API and s ready to accept some awesome functions!
At the end of this section, your code could look a little something like this:

<?php
	include("smartbots_api.php"); // Include the SmartBots API file.

	$apiKey        = "e40e365171a99nl05bdmd697273b573t"; // SmartBots API Key.
	$botName       = "Example Resident"; // The bot's full name.
	$botAccessCode = "KbYpnfa"; // The bot's access code.

	$bot = new SmartBot(); // Instansiate a new SmartBot class.
	$bot->setup($apiKey, $botName, $botAccessCode); // Pass the setup variables to the API.
?>

Next Section (Performing Actions)

Performing Actions

We've made it really easy to perform actions with your SmartBot, for example it's as simple as $bot->login(); to log in your bot! We'll take a look at all of the different actions and the different ways in which you can use them below:

To send an Instant Message from your bot, you use the im() method on your $bot variable. For example the below will send an IM to GTASkinCentral Resident with a message of "Hello world!".

$bot->im("GTASkinCentral Resident", "Hello World!"); // Send an IM to GTASkinCentral Resident.

If you need to see the response that the bot gives after the action has been executed, it's as simple as calling the response() method. This method returns the result as an array, however if you would like the raw string format, directly from the SmartBots server, simply use response(TRUE) instead.

print_r($bot->response()); // Get the bot's response in array format.

Array (
	[result] => OK
	[action] => im
)

or in string format:

echo $bot->response(TRUE); // Get the bot's response in query string format.

result=OK&action=im

Again, we can use a simple 'if' statement to see if an acton was successful or not. This is done by checking whether or not the 'result' parameter in the response is set to TRUE or FALSE.

if($bot->im("GTASkinCentral Resident", "Hello World!") == TRUE) { // If the action was successful.
	echo "Success!".
} else { // If the action failed.
	echo "Fail!".
}

As you may be aware, SmartBots also has a number of commands which return a lot of information. For example, to find out an avatar's name from their UUID or key, you can use the key2name() method. You can also pass in custom variables this way. All methods accept one custom variable at the end of the action's default variables (see below).

$bot->key2name("4d9ce772-d3ee-4cce-9555-bfb06ffcb228", "Custom Text"); // Send the key2name command.
print_r($bot->response()); // Print the result.
}

Array (
	[action] => key2name
	[result] => OK
	[key] => 4d9ce772-d3ee-4cce-9555-bfb06ffcb228
	[name] => gtaskincentral resident
	[custom] => Custom Text
)

Your SmartBot is now able to accept commands from you!
At the end of this section, your code could look a little something like this:

<?php
	include("smartbots_api.php"); // Include the SmartBots API file.

	$apiKey        = "e40e365171a99nl05bdmd697273b573t"; // SmartBots API Key.
	$botName       = "Example Resident"; // The bot's full name.
	$botAccessCode = "KbYpnfa"; // The bot's access code.

	$bot = new SmartBot(); // Instansiate a new SmartBot class.
	$bot->setup($apiKey, $botName, $botAccessCode); // Pass the setup variables to the API.

	$bot->im("GTASkinCentral Resident", "Hello World!"); // Send an IM to GTASkinCentral Resident.

	$bot->key2name("4d9ce772-d3ee-4cce-9555-bfb06ffcb228", "Custom Text"); // Send the key2name command.
	print_r($bot->response()); // Print the result.
?>

Next Section (Multiple Bots)

Multiple Bots

If you're familiar with Object-Orientated PHP, you've most likely already worked this out, however you can actually have multiple bots interacting with each other at once, in one single script! The below code demonstrates how two bots will IM each other, and then echo their responses to the screen!

<?php
	include("smartbots_api.php"); // Include the SmartBots API file.

	$apiKey = "e40e365171a99nl05bdmd697273b573t"; // SmartBots API Key.

	/* Bot Number 1 */
	$bot1_Name       = "Example Resident"; // The bot's full name.
	$bot1_AccessCode = "KbYpnfa"; // The bot's access code.

	/* Bot Number 2 */
	$bot2_Name       = "Awesome Linden"; // The bot's full name.
	$bot2_AccessCode = "f9xH9oD"; // The bot's access code.

	/* Instansiate Bot 1 */
	$bot1 = new SmartBot(); // Instansiate a new SmartBot class.
	$bot1->setup($apiKey, $bot1_Name, $bot1_AccessCode); // Pass the setup variables to the API.

	/* Instansiate Bot 2 */
	$bot2 = new SmartBot(); // Instansiate a new SmartBot class.
	$bot2->setup($apiKey, $bot2_Name, $bot2_AccessCode); // Pass the setup variables to the API.

	/* Send the IMs */
	$bot1->im($bot2_Name, "Hello bot number two!"); // Send an IM.
	$bot2->im($bot1_Name, "Hello bot number one!"); // Send an IM.

	echo "Bot 1 returned '" . $bot1->response(TRUE) . "'<br>"; // Print the result from Bot 1.
	echo "Bot 2 returned '" . $bot2->response(TRUE) . "'<br>"; // Print the result from Bot 2.
?>

Next Section (Available Actions)

Available Actions

This section shows all of the available actions which you can use with this API. Currently, all API actions available from SmartBots can be used with this API.

* indicates a required parameter, the command will not work if this paramater is left empty.

Next Section (Live Demo)

Live Demo

On this page is a live demo of the SmartBots PHP API.

Sending an IM

//The code & Result will appear here once submitted.

Find Avatar's UUID, then find the Avatar's Groups (If profile allows it)

//The code & Result will appear here once submitted.

Key2Name

//The code & Result will appear here once submitted.

Name2Key

//The code & Result will appear here once submitted.

Support

Need help? Contact [email protected] if you're in need of some help!

MIT License

Copyright (c) 2016

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.