Developers (BETA)

API Documentation

Overview

The IMified platform allows anyone with basic web programming skills to quickly and easily create and run an IM Bot. IMified bots can be created by anyone for free using this API. Developers may also at any time upgrade their hosted bots to run under one or more custom screen names as well.

Creating a Bot

A bot connected to the IMified platform in its simplest form is a dynamic web page that resides on any HTTP server and listens for incoming instant messages then outputs a response. Bot 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 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.
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.
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.
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.

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.

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 with your IMified username and password to the following URL: https://www.imified.com/api/bot/.

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 XML Responses

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 XML Responses

Getting Help

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