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).
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"
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
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'
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
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"
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