IMified API

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.

botkey botkey uniquely identifies the bot that the message is being sent to.
userkey 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 Possible values are:
Jabber, AIM, MSN, Yahoo, Gtalk, Twitter or SMS
user user is the actual screen name of the user calling your bot
channel Possible values are: public or private
Default: private
Primarily used to distinguish public @replies and private direct messages for twitter
msg msg is the text of the message sent to your bot. This field is useful for quickly reading the value of the current message sent. For bots 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.
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 end user for each respective step. These variables along with the step variable can be used to maintain state in 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 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.

<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 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.

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

Example XML Responses

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.

botkey Your unique bot key.
apimethod This parameter should have a value of getAllUsers.
Network (optional) return users from a specified network. Possible values are:
Jabber, AIM, MSN, Yahoo, Gtalk, Twitter or SMS

Example post in PHP

Example XML Responses

SendMessage

Below are the required post parameters 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
Additional options for enhanced developer accounts
Instead of sending userkey(s) to send messages to users, enhanced accounts may send a user/network combination to specify the recipient
user The user's IM screen name or twitter username
network Jabber, AIM, MSN, Yahoo, Gtalk, Twitter or SMS

Example post in PHP

Example XML Responses

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.

botkey Your unique bot key.
apimethod This parameter should have a value of updateStatus.
network Possible values are:
Jabber, AIM, MSN, Yahoo, Gtalk, or Twitter
msg The status message

Example post in PHP

Example XML Responses

Getting Help

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

image Copyright © 2007-2014 IMified, LLC All rights reserved. Terms of Use | Privacy Policy