Messaging (beta)

Distinct Instant Messaging engine API - revision 63

This documentation describes the methods of interaction with the Instant Messaging API. Queries are HTTP GET and/or POST (REST like) and responses are in XML format (exception: binary for pictures).

Table of contents
4.1 Signals related to messages



1. Authentification and access, basics

To access:

a) You will receive a base url (ie: http://im-engine.distinct.ro:8089/)
and
b) a security token to be added as a parameter to any request HTTP request (ie &token=dsdfgdfgdgwewe3423dsaaaa)

A request url looks like this:
http://im-engine.distinct.ro:8080/signals/getall?keep=1

Response:

HTTP response code:
success = 200 - normal
not found = 404 - no such API call
forbiden = 403 - wrong token

Example 200 response body:



Example 404 response body:



Content-type
Usually "Content-type: text/xml" with one exception ("text/png" when retriving icons)

Note:
- if you cannot access at all the base url you received from us (TCP errors), probably your IP address is not whitelisted, check your source ip and contact us if necessary


2. Receiving events (signals) from engine (PULL)
Description: retrieve the events (also called signals) queue from the application engine

Url format:
http://im-engine.distinct.ro:8080/signals/getall

Parameters:
keep = 0 or 1, optional, default = 0, don't delete queue after retriving (used mostly for automated monitoring)

Notes:
- number of signals in queue is limited to 150, if this number is reached the oldest entries are deleted

XML format:

Example: message received from user - ReceivedImMsg:


Description:
- sender:  name of the contact who triggered the event
- message: the string message received from that user (if exists)


or 

Example: Another type of event:


Description:
- signal_name: see bellow the list of signals (ie: ReceivedImMsg (message from user) or AccountAuthorizationRequested (incoming add buddy request)
undocumented signals, if any show up, will be ignored
- timestamp: - unix timestamp, timezone GMT, (seconds.microseconds) when the signal was raised
- timestamp_friendly: - optional, timestamp as string, GMT
- account: the name of the account related to the event (format protocol::username)
- buddy: name of the contact related to the event (if any), string

Notes:
- undocumented fields, if any, will be ignored


Example:
curl "http://im-engine.distinct.ro:8081/signals/getall?keep=1&token=60d4288ff4e04f177e2facc9662a174d98b4253bc083c4a29f"

3. Receiving events (signals) from engine (PUSH)
Description: The engine can PUSH signals to your system as they happen to a url set by you (see /accounts/setpreference).
Notifications ar done via HTTP, using POST method. Current signals queue is sent in XML format via the "content" variable.

Sample PHP script for the receiving side:



Notes:
- supports HTTP Basic Auth (embed user/password in url)
- default request timeout is 10 seconds
- if a request doesn't receive http response code OK (HTTP 200 OK) will consider the events undelivered and keep them
- when a new signal shows up, the engine will try to send the old undelivered events first then the new one
- outgoing connections from our systems are initiated from the ip of the host im-engine.distinct.ro
- the two methods for receiving signals (PULL and PUSH) can be used in the same time (there is a locking mechanism which prevents overlaping/duplication of signals received)



4. Events (Signals) list
Description: reference of signals which can be generated by system
4.1 Signals related to messages
4.1.1 ReceivedImMsg
Description: a message was received

Example:


where:
- sender:  name of the contact who triggered the event
- message: the string message received from that user (if exists)

4.2 Signals related to accounts

4.2.1 AccountAuthorizationRequested
Description: a user asked to add us in his list

Example:


4.2.2 AccountAuthorizationGranted
Description: the permission to add us was granted to a user 

Example:


Note: this signal doesn't show up if the autoaddbuddy feature is on (default)


4.2.3 AccountAuthorizationDenied
Description: the permission to add us was denied to a user 

Example:

Note: this signal doesn't show up if the autoaddbuddy feature is on (default)


4.3 SavedStatusChanged
Description: generated when our status is changed



Notes:
 - status = numeric status
 - status_alfanumeric =  alphanumeric status  (ie: away, available) - see /accounts/setstatus
 - status_message = the alphanumberic status message, if any

4.4 Signals related to contacts

4.4.1 BuddyStatusChanged
Description: un contacts change its status

Example:


Notes:
- old_status = old status alphanumeric (ie: away, available) - see /accounts/setstatus
- old_status_message = old status message (if any)
- status = status-ul alphanumeric (ie: away, available) - see /accounts/setstatus
- status_message = status message (if any)

4.4.2 BuddyIdleChanged
Description: a contact's idle status or idle time has been updated

Example:
				

Notes:
- idle = contact is idle, 0 or 1
- old_idle = before, contact was idle, 0 or 1 (idle update)

4.4.3 BuddySignedOn
Description: a contact signed on

Example:


4.4.4 BuddySignedOff
Description: a contact signed off

Example:


4.4.5 UpdateIdle
Description: global idle time for current instance was updated, used mostly as keepalive indicator for testing

Example:


4.4.6 BuddyAdded
Description: a contact was added in our list

Example:


4.4.7 BuddyRemoved
Description: a contact was removed from our list

Example:
 

4.4.8 BuddyIconChanged
Description: a contact's icon (avatar) was changed

Example:
		      		     

4.5 Signals related to connections
4.5.1 SigningOn
Description: one of our accounts is logging in

Example:
		    

4.5.2 SignedOn
Description: one of our accounts logged in

Example:


4.5.3 SigningOff
Description: one of our accounts is logging off

Example:
		    

4.5.4 SignedOff
Description: one of our accounts signed off

Example:
		    

4.5.5 ConnectionError
Description: one of our accounts raised a connection error

Example:
	      

Notes:
error = numerical error 
error_message = alphanumerical error message

Table: Connection errors 
6 = You have signed on from another location
0 = Error reading from login.yahoo.com: Input/output error


See also reconnect_after_error option in /preferences/set


5. Sending messages
Description: send instant messages to contacts

URL format:
http://im-engine.distinct.ro:8080/conversations/imsend

method: POST

Parameters:

message: message text (urlencoded):
user: destination username
account: name of the account to use (ex: yahoo::testbot2)

return values:


or



Example:
 curl -d "message=hello from bot&user=derbot&account=yahoo::testbot" http://im-engine.distinct.ro:8080/conversations/imsend


6. Send buzz
Description: send instant message with a buzz to contacts

Warning: Yahoo Messenger limits the number of 'buzz' messages allowed to
about 1/minute. If the message is lost due to those filters indication about
this will show up in error code.

URL format:
http://im-engine.distinct.ro:8080/conversations/imsendbuzz

method: POST

Parameters:

user: destination username
account: name of the account to use (ex: yahoo::testbot2)

return values:



or



Ex:

 curl  -d "user=derbot&account=yahoo::distinct_testbot" http://im-engine.distinct.ro:8080/conversations/imsendbuzz


7. Add buddy
Description: add a buddy to our list

URL format:
http://im-engine.distinct.ro:8080/accounts/addbuddy

method: POST

Parameters:

user: name of the user to add
account: name of the account to use when adding (ie: yahoo::distinct_testbot2)
group: name of the group to add user into, it will be created if it doesn't  exist


return values:



or



Example:

 curl  -d "user=derbot&account=yahoo::distinct_testbot2&group=friends" http://im-engine.distinct.ro:8080/accounts/addbuddy


8. Remove buddy
Description: remove a buddy from our list

URL format:
http://im-engine.distinct.ro:8080/accounts/removebuddy

Note: at least in Yahoo! Messenger network, even if you remove a user for
list he/she will still be able to see your status (by yahoo design). 
Future feature 'block user' will overcome this 

method: POST

Parameters:

user: username to delete
account: name of the account to use when deleting (ie: yahoo::distinct_testbot2)
group: name of the group of the user our list, it will be created if it doesn't exist

return values:



or



Example:

 curl  -d "user=derbot&account=yahoo::distinct_testbot2&group=friends" http://im-engine.distinct.ro:8080/accounts/removebuddy

Note:
- bugs, hangs sometimes

9. Set status
Description: sets status and status message on all accounts


URL format:
http://im-engine.distinct.ro:8080/accounts/setstatus

method: POST

Parameters:

status: integer, numeric code for status  (ie: 2=available, 5=away, etc)
message: alphanumeric, optional, a message text

Table: status codes

unset = 0
offline = 1
available = 2
busy = 3
invisible = 4
away = 5
extended away = 6
mobile = 7
tune = 8

Return values:



or



Example:

 curl  -d "status=5&message=I'am very away" http://im-engine.distinct.ro:8080/accounts/setstatus



10. Get current status
Description: gets current status (common to all accounts)


URL format:
http://im-engine.distinct.ro:8080/accounts/getstatus

method: POST

Parameters:

account: required but not used yet

Notes:
- see list of status codes in /accounts/setstatus


Return values:



or



Example:

 curl  -d "account=distinct_testbot2" http://im-engine.distinct.ro:8080/accounts/getstatus


11. Buddies list
Description: gets the current list of contacts and contacts details

URL Format:
http://im-engine.distinct.ro:8081/buddies/getall

method: POST

Parameters:

account: optional (ie: yahoo::distnct_testbot2)
status_message_regex: optional, a regular expresion to match on status_message (see bellow), filters only the matched entries
group: optional, return users only from this group, (not case sensitive), if this parameters is missing or it's set to 'allgroups' all groups will be returned
online: optional, 1 - return only online users (see bellow 'online'), 0 - all
avaliable: optional, 1 - returns only available users (see bellow: status_is_available), 0 - all
buddy_name: optional, return just this buddy, if you use this option parameter account is required
aggresive = optional, 0 or 1, default 0, tries to get the most up to date status/icons, takes longer


Return values:



or



where:
name: nickname buddy
online: 0 or 1, if it's logged in
icon_url: url from where you can retrive user icon (see buddies/geticon)
alias: alias the user set for himself
account: name of the account this user belongs to
group: name of the groups this user belongs to

Non-empty fields when user is online:

idle: 0=non-idle or 1=idle
idle_since: since when is idle (unix timestamp)
login_time: login time  (unix timestamp) - not available yet
status_alfanumeric: away, busy, brb, etc.
status_is_available: 1 - if user has a 'available to talk status' (available, invisible) and  0 otherwise (away, busy, etc)
status_message: status message, is exists


Example:

url  -d "account=yahoo::distinct_testbot2&online=0&group=autoadded&available=0&status_message_regex=edi&message=test mass regex edition 445" http://im-engine.distinct.ro:8081/buddies/getall

Notes:
- if no interaction with a user took place recently, the status and icon_url fields might be outdated, see parameter 'aggresive'


12. Autoadd buddy feature

The engine has a component to automatically add in list a buddy who adds us
or sends us a message. This is active by default.

After adding a user a customizable message is sent to him. (see /preferences/set)


13. Send mass instant message
Description: send a message to more than one user at a time

URL format:
http://im-engine.distinct.ro:8080/conversations/imsendmass

method: POST

Parameters:

message: text of the message to send (urlencoded): 
group: name of the group to get destination user from, 'allgroups' gets all groups
account: use only this account, optional, (ie: yahoo::distinct_testbot2)
online: 1 - send just to online users, 0 - send to all
available: 1 - send just to available users (not away, not invisile, etc), 0 - send to all
status_message_regex: optional, send message just to users matching this regular expresion 

Return values:



or



Example:
 curl  -d "account=yahoo::distinct_testbot2&online=0&group=autoadded&available=1&status_message_regex=edi|summer&message=test mass regex edition 449" http://im-engine.distinct.ro:8081/conversations/imsendmass



14. Get current accounts in this instance
Description: returns a list of configured accounts (including username, protocol, enabled status, connected status)

URL format:
http://im-engine.distinct.ro:8080/accounts/getall

method: POST

Parameters:
n/a


Return values:



or

				  


Example:
 curl  http://im-engine.distinct.ro:8080/accounts/getall


15. Set account enabled/disabled
Description: enables or disables specified account

URL format:
http://im-engine.distinct.ro:8080/accounts/setenabled

method: POST

Parameters:
account: name of the account (ex: yahoo::distinct_testbot2)
enabled: 0=disabled sau 1=enabled


Return values:



or


				  
Example:
curl  -d "account=yahoo::distinct_testbot2&enabled=1" http://im-engine.distinct.ro:8081/accounts/setenabled



16. Set account connected/disconnected
Description: connects or disconnects an account from the network

URL format:
http://im-engine.distinct.ro:8080/accounts/setconnected

method: POST

Parameters:
account: name of the account (ex: yahoo::distinct_testbot2)
connected: 0=disabled sau 1=enabled


Return values:



or


				  
Example:
curl  -d "account=yahoo::distinct_testbot2&connected=1" http://im-engine.distinct.ro:8081/accounts/setconnected



17. Get avatars
Description: returns a icon (binary, png format)


URL format:
http://im-engine.distinct.ro:8080/buddies/geticon?icon=6479407178b33b3ce88dd076e200b8d2df7d79a0.png

method: GET

Parameters:
icon = name of the icon file (get it from  /buddies/getall or /accounts/getall)


Return values:



or

image in png format (Content-type: image/png)

				  
Example:

curl "http://im-engine.distinct.ro:8081/buddies/geticon?icon=6479407178b33b3ce88dd076e200b8d2df7d79a0.png" > file.png


18. Create account
Description: creates an account in the local instance 

URL format:
http://im-engine.distinct.ro:8081/accounts/create?username=dorel&password=gigel&protocol=yahoo&alias=doru&enabled=0

method: POST

Parameters:
username: username, string
password: password, string
protocol: protocol id  (see bellow), string
alias: local user alias
enabled: 1= activate this account after creation


Return values:



or



Table: protocol names

yahoo = Yahoo Messenger
gg = Gadu-Gadu
msn = MSG Messenger / Windows Live Messenger
jabber = Jabber protocol (including GTalk)
icq = ICQ
oscar = Oscar
irc = Internet Relay Chat


Example
curl  http://im-engine.distinct.ro:8081/accounts/create?username=distinct_testbot&password=gigel&protocol=yahoo&alias=doru&enabled=0

19. Modifiy account
Description: modifies one ore more properties of an account

URL format:
http://im-engine.distinct.ro:8081/accounts/modify?account=yahoo::distinct_testbot&username=dorel&password=gigel&protocol=yahoo&alias=doru

method: POST

Parameters:
account = name of the account to modify(ex: yahoo::distinct_testbot2)
username = optional, username
password = optional, password
protocol = optional, protocol id (see /accounts/create for list)
alias = optional, local user alias


Return values:



or



				  
Example:
curl  "http://im-engine.distinct.ro:8081/accounts/modify?account=yahoo::distinct_testbot&username=dorel&password=gigel&protocol=yahoo&alias=doru"

20. Remove account
Description: Removes an account

URL format:
http://im-engine.distinct.ro:8081/accounts/delete?account=yahoo::distinct_testbot

method: POST

Parameters:
account = name of the account (ex: yahoo::distinct_testbot2)

Return values:



or



				  
Example:
curl  "http://im-engine.distinct.ro:8081/accounts/delete?account=yahoo::distinct_testbot


21. Set preference value
Description: sets a local preference for this engine instance

URL format:
http://im-engine.distinct.ro:8081/preferences/set

method: POST

Parameters:
name = name of the preference
value = value of the preference

Return values:



or



Valid preferences are:

secure_token = token used to authorize access to this instance (&token=) 

autoadd = 0,1 - if a user add or im us, add him to our list automatically ? (default '1')
autoadd_group =  into what group to autoadd the user (default 'Autoadded')
autoadd_message = optional, a text message to be sent to user after autoadd

post_push_url = optional, a URL where to send signals as they are raised (PUSH) (see also /signals/getall), support username/password for http embeded in url

reconnect_after_error = 0,1 - what to do if an active account gets a connection error, default=1 (reconnect) 
reconnect_attempts = how many reconnect attempts to do (default 3)
reconnect_sleep = delay between reconnects in seconds (default 20)

yo_1000_active = optional, 0 sau 1, default 1, if an Yahoo! account has more than 990 users in it's list, the next users autoadded will be added by secondary accounts (if any, if active)

yo_1000_custom_message_primary =  optional, what message to send to the autoadded user from the main account, if it's added via a secondary account , default: "Notice: Due to some Yahoo Messenger limitations i can't add you to my primary list so i'll add you through <> id "
                               supports macro <<secondary_id>> which will be replaced by secondary id's useranme
yo_1000_custom_message_primary =  optional, what message to send to the autoadded user from the secondary account, if added via a secondary account, default:  "Notice: Thanks for adding <> to your list.
                               supports macro <<primary_id>> which will be replaced by primary id's useranme



Example:
curl  "http://im-engine.distinct.ro:8081/preferences/set?name=test&value=milk"



22. Get preference value
Description: Return a preference value

URL format;
http://im-engine.distinct.ro:8081/preferences/get

method: POST

Parameters:
name = name of the preference


Return values:



or



Example:
curl  "http://im-engine.distinct.ro:8081/preferences/get?name=test"


23. Set icon
Description: Upload and set a icon for all accounts

URL format:
http://im-engine.distinct.ro:8081/accounts/seticon

method: POST

Parameters:
icon_bin = binary content of the icon


Return values:



or



Notes:
- icon size must be less than 25k and has be in PNG format
- temporary problem: active accountss will be disconnected/connected in order to set the new icon
(Warning: Yahoo!, at least, has a rate limit for the number of connects/disconnects per time period)


Example:
curl  -F icon_bin=@./icon.png http://im-engine.distinct.ro:8081/accounts/seticon


24. YO1000 feature (Yahoo over 1000 users in contacts list)
Description: Yahoo! Messenger has a server-side limit of about ~1000 entries
for the contacts list of one account. In order to overcome this we can use
additional accounts grouped in a 'set'.


If:
a)  yo1000_active preference is 1
and
b) there are enabled and connected more accounts with similar name (ie: main = id, secondary = id1,id2,id3,id4 .. to id9)
and
c) the account used for autoadd has more than 990 users in list


then:

The engine will find a next secondary id with less than 990 users in list
and add the user from that account.


furthermore, additional clarification messages will be sent to the user:


a) from the main account (ex: id), an addtional instant message will be sent to the user (customizable in preference, see preference yo_1000_custom_message_primary),
text supports the macro <<secondary_id>> which will be replaced by secondary id's useranme

b) from the secondary account (ex: id2) an instant message will be sent to the user (customizable in preferences, see preference yo_1000_custom_message_secondary) 
text supports macro <<primary_id>> which will be replaced by primary id's useranme