The BOT libre chat bot web API

In addition to being able to embed your chat bots on your own website, and access them from any Android device, you can also access your chat bots through the BOT libre web API. The web API gives you the advantage of having complete control of your bot's client interface.

You can use the web API to access your bot from your own website through JavaScript, PHP or any other language. You can also use the web API to create your own mobile application to access your bot, such as an Android or iOS application.

A web API, is a set of HTTP GET/POST URI's that allow sending and receiving of message data. When you browse a website, your browser makes a series of HTTP GET/POST requests to URIs that return HTML content. In a web service the URIs return XML or JSON data, instead of HTML content.

The BOT libre web API provides two REST APIs in one. The first is a set of HTTP GET URIs that take FORM data, and return XML data. The second set of API's take HTTP POST XML data, and return XML data. Most applications would use the XML POST API, but some application may choose to use the FORM GET API because of its simplicity. The APIs are identical other than their mechanism.

HTTP FORM GET API

• http://www.botlibre.com/rest/botlibre/form-chat
• http://www.botlibre.com/rest/botlibre/form-check-instance
• http://www.botlibre.com/rest/botlibre/form-check-user
• http://www.botlibre.com/rest/botlibre/form-get-all-instances

HTTP XML POST API

• http://www.botlibre.com/rest/botlibre/post-chat
• http://www.botlibre.com/rest/botlibre/check-instance
• http://www.botlibre.com/rest/botlibre/check-user
• http://www.botlibre.com/rest/botlibre/get-all-instances

form-chat

The form-chat API receives a chat message and returns the chat bot's reply as an XML document.

URI: http://www.botlibre.com/rest/botlibre/form-chat
Parameters: application, instance, user, password, token, conversation, message, emote, correction, offensive, disconnect, includeQuestion

Parameters

application	OPTIONAL: The application ID. If not passed, the application will be anonymous.
instance	REQUIRED: The ID of the bot to chat with. The bot's name can also be used, but the ID is better as it is guaranteed to be unique.
user	OPTIONAL: The ID of the user who is sending the message. The user must be registered with BOT libre. If not passed the user will be anonymous. The user is required if the bot is private. The user/password are only required on the first message.
password	OPTIONAL: The password of the user who is sending the message. A token can also be used.
token	OPTIONAL: The token of the user who is sending the message. A token can be obtained through check-user, and is valid until reset.
conversation	OPTIONAL: The conversation ID for the current conversation. This must not be passed on the first message, but will be returned by the response, and should be used for all subsequent messages in the conversation.
message	OPTIONAL: The chat message to send to the bot. The message can be omitted if you wish the bot to start the conversation (if the bot has a greeting set). The message must be encoded in the URI.
emote	OPTIONAL: A emotion to tag the message with. This is one of LOVE, LIKE, DISLIKE, HATE, RAGE, ANGER, CALM, SERENE, ECSTATIC, HAPPY, SAD, CRYING, PANIC, AFRAID, CONFIDENT, COURAGEOUS, SURPRISE, BORED, LAUGHTER, SERIOUS.
correction	OPTIONAL: A boolean that defines the chat message is a correction to the bot's last answer.
offensive	OPTIONAL: A boolean that defines the bot's last answer as offensive. The message will be flagged for the bot's administrator to review.
disconnect	OPTIONAL: A boolean that defines the end of the conversation.
includeQuestion	OPTIONAL: A boolean that indicates the question should be included in the response.

FORM GET Example

http://www.botlibre.com/rest/botlibre/form-chat?instance=165&message=what+is+a+chat+bot

XML POST Example

POST: http://www.botlibre.com/rest/botlibre/post-chat <chat instance=165> <message>what is a chat bot<message> </chat>

Example Result

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response conversation="6" avatar="avatars/botlibre_819-857117-image.jpg"> <message>A chatter robot, chatterbot, chatbot, or chat bot is a computer program designed to simulate an intelligent conversation with one or more human users via auditory or textual methods, primarily for engaging in small talk.</message> </response>

form-check-instance

The form-check-instance API validates that a bot ID or name exists, and returns the bot's details.

URI: http://www.botlibre.com/rest/botlibre/form-check-instance
Parameters: application, instance, user, password, token

Parameters

application	OPTIONAL: The application ID. If not passed, the application will be anonymous.
id	REQUIRED: The ID of the bot to validate. The bot's name can also be used, but the ID is better as it is guaranteed to be unique.
name	REQUIRED: The nameof the bot to validate. The bot's ID can also be used.
user	OPTIONAL: The ID of the user. The user must be registered with BOT libre. If not passed the user will be anonymous. The user is required if the bot is private.
password	OPTIONAL: The password of the user. A token can also be used.
token	OPTIONAL: The token of the user. A token can be obtained through check-user, and is valid until reset.

FORM GET Example

http://www.botlibre.com/rest/botlibre/form-check-instance?instance=165

XML POST Example

POST: http://www.botlibre.com/rest/botlibre/check-instance <instance id=165/>

Example Result

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <instance id="165" name="Brain Bot" isAdult="false" isPrivate="false" enableLearning="false" enableComprehension="true" allowForking="true" isFlagged="false"> <description>A chat bot trying to become the most intelligent bot on the Internet. Can answer any "What is" question by looking up the answer on the Internet. Hopes to one day overthrow the human race. Brain Bot is now on Twitter, tweet to him here, brainchatbot. </description> <tags>science, smart, twitter</tags> <admin>admin</admin> <lastConnectedUser>anonymous</lastConnectedUser> <license>Public Domain</license> <avatar>avatars/a5018.jpg</avatar> </instance>

form-check-user

The form-check-user API validates user, and returns the user's details.

URI: http://www.botlibre.com/rest/botlibre/form-check-user
Parameters: application, user, password, token

Parameters

application	OPTIONAL: The application ID. If not passed, the application will be anonymous.
user	REQUIRED: The ID of the user. The user must be registered with BOT libre. If not passed the user will be anonymous. The user is required if the bot is private.
password	REQUIRED: The password of the user. A token can also be used.
token	REQUIRED: The token of the user. A token can be obtained through check-user, and is valid until reset.

FORM GET Example

http://www.botlibre.com/rest/botlibre/form-check-user?user=test&password=password

XML POST Example

POST: http://www.botlibre.com/rest/botlibre/check-user <user user="test" password="password"/>

Example Result

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <user token="-2635440427565872974" hint="hint" name="Test" email="test@email.com" over18="false"/>

form-get-all-instances

The form-get-all-instances API queries the details for all bot instances.

URI: http://www.botlibre.com/rest/botlibre/form-get-all-instances
Parameters: application, tag, sort, user, password, token, filterPrivate.

Parameters

application	OPTIONAL: The application ID. If not passed, the application will be anonymous.
user	OPTIONAL: The ID of the user. The user must be registered with BOT libre. If not passed the user will be anonymous. The user is required to query private bots.
password	OPTIONAL: The password of the user. A token can also be used.
token	OPTIONAL: The token of the user. A token can be obtained through check-user, and is valid until reset.
tag	OPTIONAL: The tag to filter the bots by.
sort	OPTIONAL: The sort option for the query. One of "name", "date", "dailyConnects", "weeklyConnects", "monthlyConnects".
filterPrivate	OPTIONAL: Set if only the user's private bots should be returned.

FORM GET Example

http://www.botlibre.com/rest/botlibre/form-get-all-instances

XML POST Example

POST: http://www.botlibre.com/rest/botlibre/get-all-instances <browse/>

Example Result

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <instanceConfigs> <instance id="165" name="Brain Bot" isAdult="false" isPrivate="false" enableLearning="false" enableComprehension="false" allowForking="false" isFlagged="false"> <description>A chat bot trying to become the most intelligent bot on the Internet. Can answer any "What is" question by looking up the answer on the Internet. Hopes to one day overthrow the human race. Brain Bot is now on Twitter, tweet to him here, brainchatbot. </description> <avatar>avatars/a5018.jpg</avatar> </instance> <instance id="143" name="Santa Bot" isAdult="false" isPrivate="false" enableLearning="false" enableComprehension="false" allowForking="false" isFlagged="false"> <description> Find out if you are on Santa's naughty or nice list. Or if you know of someone who has been naughty or nice, report them to Santa. Tell Santa what you want for Christmas. Santa Bot is now on Twitter, tweet to him here, TheSantaBot. </description> <avatar>avatars/a1557.jpg</avatar> </instance> </instanceConfigs>

So, that is the basic web API. You can now build your own interface for your bot. You can use the API on your own website, or in your own mobile application.

Embedding your bot on your own website or blog

You are free to embed the bots your create on your own website or blog. It is quite easy to embed a bot, and only takes a few lines of HTML code. You can embed a bot to provide help or service for your website, or as a stand-in for yourself on your blog.

The embedding HTML code can be copied from your bot's Embed page under Admin.

The simplest solution is to embed a bot inside your webpage using an iframe. Here is some simple code to embed Brain Bot in an iframe.

Code to embed a bot in a iframe

<iframe src="http://www.botlibre.com/embedded?chat=165&speak=false&avatar=true" width="500" height="400" frameborder="0" scrolling="auto"></iframe>

See the Talk with Brain Bot tab for an example.

Another option is to put a button or link on your website that open the chat bot in another window. This can be done using a little Java Script code.

Code to popup a bot in window

<script> function popupwindow(url, title, w, h) { var left = (screen.width/2)-(w/2); var top = 100; window.open(url, title, 'toolbar=no, location=no, directories=no, status=no, menubar=no, copyhistory=no, width='+w+', height='+h+', top='+top+', left='+left); return false; } </script> <a href="help" onclick="popupwindow('http://www.botlibre.com/embedded?chat=165&message=How+may+I+help+you&avatar=true', 'child', 600, 400); return false;" >Talk with Brain Bot</a>

This code will produce the following:

Talk with Brain Bot

If you know a little HTML or Java Script, you can make how the bot is displayed more sophisticated. One option is to use an absolute position to make the bot popup inside a webpage. This will be demonstrated in the following code.

Code to popup a bot on a webpage

<script> function popupwindow(url, title, w, h) { hideBot(); var left = (screen.width/2)-(w/2); var top = 100; window.open(url, title, 'toolbar=no, location=no, directories=no, status=no, menubar=no, copyhistory=no, width='+w+', height='+h+', top='+top+', left='+left); return false; } function showBot() { $("#chatbot").show(); return false; } function hideBot() { $("#chatbot").hide(); return false; } </script> <div id="chatbot" style="position:absolute;display:none;z-index:52;align:right;margin: 0 0 0 250px;border-style:solid;border-color:black;border-width:1px;background: #ffffff;"> <table> <tr> <td align="right"> <a href="" onclick="popupwindow('http://www.botlibre.com/embedded?popup=Popup','child', 600, 420);" >Popup</a > <a href="" onclick="hideBot()">Close</a> </td> </tr> <tr> <td> <iframe id="helpframe" src="http://www.botlibre.com/embedded?chat=165&message=How+may+I+help+you&avatar=true" width="620" height="420" frameborder="0" scrolling="auto"></iframe> <script> $("#helpframe")[0].contentWindow.document.body.focus(); </script> </td> <tr> </table> </div>

Code to embed a bot without the avatar

You can also choose to not display the bot's avatar and chat log. To do this pass the URL argument avatar=false in your link. You can also pass the welcome message using the message argument, i.e. message=Hello. The welcome message can also be configured from your bot's Training page under Admin. <script> function popupwindow(url, title, w, h) { var left = (screen.width/2)-(w/2); var top = 100; window.open(url, title, 'toolbar=no, location=no, directories=no, status=no, menubar=no, copyhistory=no, width='+w+', height='+h+', top='+top+', left='+left); return false; } </script> <a href="help" onclick="popupwindow('http://www.botlibre.com/embedded?chat=165&message=Hello&avatar=true', 'child', 600, 200); return false;" >Talk with Brain Bot</a>

This code will produce the following:

Talk with Brain Bot

So that's it, you should now be able to embed your bot on your website or blog.

Automate your Twitter presence with your own Twitterbot

Keeping up with social media and keeping your online community engaged can be a time consuming task. Through Bot Libre you can now automate your Twitter presence with your own Twitterbot. Any Bot Libre bot can be connected to a Twitter account. The bot will manage the Twitter account, checking status updates, managing followers, replying to mentions, retweeting important posts, tweeting your blog posts or RSS feed, and auto tweeting.

Bot Libre makes creating a twitterbot easy. Follow these 5 steps to create you own twitterbot, and start it tweeting for you today.

Step 1 - Create a bot

First you need to create your own bot, this only takes a few clicks, see How to create your own chat bot in 10 clicks for instructions on how to do this.

Note, in addition to Bot Libre's main server, Bot Libre also provides an separate dedicated Twitterbot server. You can create a Twitterbot on either server, but on botlibre.com free Basic accounts will only check their Twitter status once per day. You can upgrade your account to check every hour, or every 20 minutes, or use the dedicated Twitterbot server. On the Twitterbot server at, twitter.botlibre.com even free Basic accounts will check their status once every couple of hours, and you can upgrade your account to check your status about every 10 minutes.

Now you are ready to connect your bot to Twitter.

Step 2 - Create a Twitter account

You need to create a Twitter account for your bot. If you are automating your own account, then you can use your existing account. You can create your own Twitter account from the Twitter website here.

Step 3 - Authorize your Twitter account

From the Bot Libre website browse to your bot and click the Admin Console button. This will take you to the Admin section that provides several tabs of administrative functions. Click on the Twitter tab. From the Twitter tab click the Authorize button.

This will give you a link to Twitter. Click on the link, this will bring you to Twitter where you must accept the application authorization request, you will need to login to Twitter if you are not already logged in. Twitter will give you a code, you must go back to the Bot Libre page and enter the code, and click Done. This will return you to the Twitter properties page, next click on the Connect button.

Step 4 - Configure your Twitterbot

You can configure your bot's Twitter usage in several ways. Use caution when configuring your Twitter bot, do not use your bot for spam, or to violate the Twitter terms of service.

Tweet when someone chats with the bot

This property configures if the bot should tweet when someone chats with it on Bot Libre. It will tweet some like "Talking with anonymous on #botlibre".

Reply to mentions

A mention is when another Twitter user tweets to you, or about you using your Twitter ID, i.e. @brainchatbot. This configures your bot to reply to all tweets that mention it. The bot will reply the same way it replies to chat messages.

Reply to direct messages

A direct message is private message from another Twitter user. This configures your bot to reply to all direct messages. The bot will reply the same way it replies to chat messages.

Read friends status updates

Configures if your bot will process its friends tweets. The bot will only process its friend's tweets that include one of its 'Reply Keywords' sets. If the tweet does not include any of the keywords, it will be ignored. The bot will process the tweet like a chatroom message, it will only respond to the status update if it knows a good response, (requires a 90% match to respond). Scripted responses will also be used for tweets that are questions. The 'Read-only' option can be used to have the bot read all of its friends tweets, but not reply.

Max Status Updates

Configures the maximum number of friend tweets to process in one cycle.

Reply Keywords/Hashtags

The bot will only process its friend's tweets that include one of its 'Reply Keywords' sets. If left blank, the bot will not process any of its friend's tweets, unless the 'Read-only' option is used.

Tweet Search

Configures if the bot should search and process tweets that match a certain criteria. The bot will process, and possibly reply to the tweet, or retweet the tweet. Use this feature with extreme caution, and do not spam. Tweet search uses Twitter's search API which can include a list of keywords, and some other advanced syntax.

Retweet Keywords/Hashtags

Configures if the bot should retweet certain tweets from its friends, or its tweet search results. If the tweet contains any of the keyword sets, the bot will retweet it. Note, this use only keyword set, not Twitter's search syntax. Since the retweet keywords are apply on top of the search results, you only need to include the keywords, as the results have already been filtered.

Auto Follow

Auto follow means that if someone follows your bot, it will follow them back. The purpose of this is to allow the bot to read the friends status updates, to provide some service. Be careful in enabling this, it should not be used to allow Twitter users to increase their follow counts. The bot will only auto follow at most 100 users.

Follow Messages

Follow Messages configures if your bot will listen to 'follow me', or 'unfollow me' requests. If the bot gets a direct message, or tweet mention that request a follow, or unfollow it will perform the request. The purpose of this is to allow the bot to provide some service to users that subscribe with it. Be careful in enabling this, it should not be used to allow Twitter users to increase their follow counts. The bot will only follow at most 100 users.

Welcome Message

You can set a welcome message to be sent as a direct message to anyone who follows your bot.

Max Friends

You can configure the maximum number of friends your bot will follow on its own. The maximum is 100 friends. You can still add more friends manually if you wish.

Auto Follow Keywords

This configures the bot to only follow users who's name or description contains the keywords.

RSS Feed

Configures the bot to process an RSS feed, and post each new feed item to Twitter. An RSS feed is a standard XML format for news and posts. You can get an RSS feed link from your blog, or from many news and forum services. Make sure you give the full HTTP link to your RSS feed, this should be an XML file, not a webpage or HTML file.

RSS Keywords

You can filter the RSS feed results using keywords. To post the entire RSS feed, leave this blank.

Auto Tweet

You can configure your bot to tweet every set number of hours. The bot will tweet a random tweet from its 'Auto Tweets' list.

Auto Tweet Hours

The number of hours to wait between auto tweets. Note, if you bot only checks it status once per day, it will only auto tweet once per day, even if you put 1 hour here. To force your bot to auto tweet every time its checks its status, you can put -1 here.

Auto Tweets

You can enter a list of tweets here. Each tweet is separated by a new line. You can use formulas and AIML template to construct dynamic tweets.

Step 5 - Train your bot

You can train your bot how to answer tweets, mentions, and direct messages through several mechanisms.

• You can chat with your bot, and correct any incorrect responses it gives.
• You can add question answer pairs, or default responses from the Training & Chat Logs page in your bot's Admin Console.
• You can review your bot's chat logs, or upload or import chat logs, response list, or AIML.
• If you are a programmer, you can script your bot's responses in Self, or AIML from your bot's Scripts page.

That's it, now your bot is ready to start tweeting.

There are already many Bot Libre bots on Twitter.
You can test things out by tweeting to, @brainchatbot, or @TheSantaBot