Login | Sign Up

Overview

The IMified platform allows anyone with basic web programming skills to quickly and easily create and run an IM application more commonly known as a "BOT".

To get started you'll need to sign up for a free developers account if you haven't already done so.

Creating a Bot

An application connected to the IMified platform is in its simplest form a dynamic web page that resides on any HTTP server and listens for incoming instant messages then outputs a response. Developers may also "push" messages to users, as well as request a users presence via a REST api call to IMified's server. You specify the endpoint "url" in your applications settings.

Basic example apps in PHP and CFML can be found on our Google group. More examples are coming soon.

Receiving and Replying to Incoming IM Messages

When a user sends a message to your bot, IMified will forward the message along with some other post variables to a url on your server. The table below outlines the post variables you can expect to receive.

userkey	userkey is a unique token generated by IMified when presence is established with an IM user sending a message to your bot. This userkey uniquely identifies a user of your bot and can be used for instance, to associate the IM user with a user in your system. Userkey is variable length, no greater than 50 characters.
network	network is the IM network the user has sent the message from. Possible values are: Jabber, AIM, MSN, or Yahoo.
msg	msg is the text of the IM message sent to your bot. This field is useful for quickly reading the value of the current message sent. For bot that are command based as opposed to "menu driven", and do not need to maintain "state", the msg variable can be used to read and respond to commands sent to your bot.
valuex	value1 - valuex are the values entered by the IM user for each respective step. These variables along with the step variable can be used to maintain state in your bot.
step	step is a numeric value which represents what step the user is on and is incremented each time a call to the bot is made. For instance, when an IM user first sends a message to your bot, the step variable will be 1. The second message sent will have a step value of 2 and so on, until you reset the bot or provide a function for your user to reset the bot.

Example Hello World bot

The example below illustrates just how easy it is to create a bot. This example is coded in PHP, however you can use any scripting language or server technology to create your bot.

<?php switch ($_REQUEST['step']) { case 1: echo "Hi, what's your name?"; break; case 2: echo "Hi " . $_REQUEST['value1'] . ", where do you live?"; break; case 3: echo "Well, welcome to this hello world bot, " . $_REQUEST['value1'] . "<br>from " . $_REQUEST['value2'] . ".<reset>"; break; } ?>

Formatting your Return Text

When returning a response to an incoming IM message, you may use the <br> tag to specify line break(s). This is the only formatting element IMified will accept. Other HTML elements will not be rendered.

Using "Helper" Functions in your Response

The IMified bot API interprets helper functions like the <reset> function in the hello world example above. The table below outlines the helper functions available to you when writing your bot.

<error>	The <error> function works exactly as it sounds. Place this function in your output to force the bot user to go back a step. For instance, if your bot asks a user for a number, but a string is entered, you can reply with: You must enter a number<error>
<goto=step>	The <goto> function lets you explicitely define the step number to send the user to.
<reset>	The <reset> function will reset your bot by clearing the users step values.

Authenticating your Users Against their IM Accounts

Some bots may require that the IM user authenticate on your site before they can use your bot. While it is completely up to the bot developer how the connection is made, we have outlined some recommendations for doing so below.

• You may elect to direct your application's users to a page on your site where they can "setup" their IM acount. In this instance, you would generate a temporary code for the user, and instruct them to send that code to your bot. In your bot's logic, you would read in the userkey variable first to determine whether or not the user exists in your database. If not, you would read the msg variable to see if the message is a code generated by your system and if so, store the userkey of the IM user in your database to make the association.
• Another option is to simply read the userkey variable at the top of your bot's logic. When you see a userkey not found in your database, you can reply to the message with a link for the user to click and login to your application passing along the userkey (or a random key generated by you) in the url to make the association in your database.
• Another option is to simply ask an IM user without a userkey in your database to enter their credentials directly in their IM client. Please be aware that instant messaging is NOT a secure medium for transferring sensitive data and one of the two methods above should be used when security is paramount.

Sending Instant Messages and Requesting User Information

The IMified API offers a REST interface for sending messages to and receiving user details from the users of your bot. These two functions combined offer a simple way to see if your users are online and act accordingly.

All API calls for requesting user details and sending messages should be sent via HTTP POST to the following URL: https://www.imified.com/api/bot/.

Authentication is managed using Basic HTTP authentication. Every request must include the Authorization HTTP header with your IMified username and password.

Requesting User Details

Below are the required post paramaters you must send to receive user details for a bot user.

botkey	Your unique bot key.
apimethod	This parameter should have a value of getuser.
userkey	The userkey of the user you are requesting information on. Note: You may pass a list of userkeys seperated by comma to return more than one user.

Example post in PHP

<? $url = 'https://www.imified.com/api/bot/'; $data = array( 'botkey' => 'your_bot_key', 'apimethod' => 'getuser', 'userkey' => 'user_key', ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_USERPWD, 'account_username:account_password'); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_TIMEOUT, 100); $xml = curl_exec($ch); curl_close($ch); print_r($xml); ?>

Example XML Responses

** SUCCESSFUL REQUEST ** <rsp stat="ok"> <user> <status>Online</status> <userkey>123456789</userkey> <screenname>user_screenname</screenname> <network>AIM</network> <created>2007-09-26 13:30:25</created> <lastonline>2007-09-28 15:20:15</lastonline> <lastcall>2007-09-28 15:20:15</lastcall> </user> </rsp> ** ERROR RESPONSE ** <rsp stat="fail"> <err msg="error message text"/> </rsp>

Sending Instant Messages to your Users

Below are the required post paramaters you must send to push a message to a bot user or a list of users.

botkey	Your unique bot key.
apimethod	This parameter should have a value of send.
userkey	The userkey of the user you would like to send a message to. Note: You may pass a list of userkeys seperated by comma to send one message to multiple users.
msg	The message you'd like to send.

Example post in PHP

<? $url = 'https://www.imified.com/api/bot/'; $data = array( 'botkey' => 'your_bot_key', 'apimethod' => 'send', 'userkey' => 'user_key', // char 'msg' => 'Hello User', ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_USERPWD, 'account_username:account_password'); curl_setopt($ch, CURLOPT_POSTFIELDS, $data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_TIMEOUT, 100); $xml = curl_exec($ch); curl_close($ch); print_r($xml); ?>

Example XML Responses

** SUCCESSFUL REQUEST ** <rsp stat="ok"> <success msg="sent"/> </rsp> ** ERROR RESPONSE ** <rsp stat="fail"> <err msg="error message txt"/> </rsp>

Getting Help

We're here to help. Send us an email at help@imified.com for api support.