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.
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.
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. |
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.
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.
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. |
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.
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.
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. |
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 |
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 |
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 |
We're here to help. Send us an email at help@imified.com for api support.