Overview

The IMified platform allows anyone with basic web programming skills to quickly and easily create and run an IMR (Interactive Messaging Response) application more commonly known as a "BOT" on public IM networks and Twitter.

To get started you'll need to sign up for a free developer 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 messages then outputs a response. You specify an endpoint URL in your bots' settings. Developers may also "push" messages to users, as well as request a users presence via a REST api call to IMified's server.

Receiving and Replying to Incoming 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.

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 message, you may use HTML formatting. IMified will send both a plain text and html formatted version to an end-users IM client and will strip formatting if the endpoint is twitter. Developers should listen for the "network" form field and respond accordingly for better formatting control.

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.

Authenticating Users of your Bot

Some bots may require that the 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, or twitter account. 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 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 a user without a userkey in your database to enter their credentials directly in their 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.

API Methods

The IMified API exposes methods for sending messages, fetching user details, and updating status. 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 parameters you must send to receive user details for a bot 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); if (curl_error($ch)) { print "ERROR ". curl_error($ch) ."\n<br/>"; } curl_close($ch); print_r($xml); ?>

Example XML Responses

** SUCCESSFUL REQUEST ** <rsp stat="ok"> <user> <status>Online</status> <extendedstatus>Working on an IMified bot</extendedstatus> <userkey>123456789</userkey> <screenname>user_screenname</screenname> *deprecated <user>user_screenname</user> <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>

GetAllUsers

Below are the required post parameters you must send to receive the user details for all users of a bot as well as a user count.

Example post in PHP

<? $url = 'https://www.imified.com/api/bot/'; $data = array( 'botkey' => 'your_bot_key', 'apimethod' => 'getallusers' ); $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); if (curl_error($ch)) { print "ERROR ". curl_error($ch) ."\n<br/>"; } curl_close($ch); print_r($xml); ?>

Example XML Responses

** SUCCESSFUL REQUEST ** <rsp stat="ok"> <users count="2"> <user> <status>Online</status> <extendedstatus>Working on an IMified bot</extendedstatus> <userkey>123456789</userkey> <screenname>user_screenname</screenname> *deprecated <user>user_screenname</user> <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> <user> <status>Offline</status> <extendedstatus></extendedstatus> <userkey>123456789</userkey> <screenname>user_screenname</screenname> *deprecated <user>user_screenname</user> <network>Jabber</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> </users> </rsp> ** ERROR RESPONSE ** <rsp stat="fail"> <err msg="error message text"/> </rsp>

SendMessage

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

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); if (curl_error($ch)) { print "ERROR ". curl_error($ch) ."\n<br/>"; } 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>

UpdateStatus

For IM, updates your bot's extended status. For twitter, posts a status update.

Below are the required post parameters you must send to update a bot's status.

Example post in PHP

<? $url = 'https://www.imified.com/api/bot/'; $data = array( 'botkey' => 'your_bot_key', 'apimethod' => 'updateStatus', 'msg' => 'I am here and ready to help.', 'network' => 'AIM', ); $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); if (curl_error($ch)) { print "ERROR ". curl_error($ch) ."\n<br/>"; } curl_close($ch); print_r($xml); ?>

Example XML Responses

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

Getting Help

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