Simple API for the stickapps Instant Messenger

If you want to have deeper access to the toksta Instant Messenger and import data from your community such as friendslist or blacklist you can set up a super simple API. This API is nothing more than a little script which will be called by our chatserver.

For example: If the users clicks in the Instant Messenger to see a list of all online friends we will call your API and you simply return this users friends in your script. Then the user can see exactly the same friends in the Instant Messenger as in the community.

There are different occasions when your API will be called. The type of the occassion will be passed to your script as the GET parameter “op”. Please see the following documentation for a list of passed arguments and how the outup of your script should look like.

List all API calls which you support in your Simple API.

Arguments

• op = “supported_calls”

Return

A List of all supported calls separated by line delimiters

Example

is_blocked
get_friends
set_friend
unset_friend

Called URL e.g.: your-domain.com/stickapps.php?op=supported_calls

Is called when the users logs in at the stickapps chat server. Here you can authenticate the user. For example: compare the md5-hash of app_user_id+PASSWORD-STRING and the argument hash. Passwort-String is passed by you in the stickapps implementation script.

Arguments

• op = “auth”
• app_user_id - user_id of the user in your community
• hash - The hash combined of the user_id and your PASSWORD-STRING

Return

• 1 - on success
• 0 - otherwise

Example

1

Called URL e.g.: your-domain.com/stickapps_api.php?op=auth&app_user_id=1&hash=…

Is called when a message has been sent from one users to another. Tells whether messages from one user to another are allowed.

Arguments

• op = “is_blocked”
• from_user_id - user id of sender
• to_user_id - user id of recipient

Return

• 1 - on blocked
• 0 - otherwise

Example

1

Called URL e.g.: your-domain.com/stickapps_api.php?op=is_blocked&app_id=1&from=user1&to=user2

Is called when the users retrieves the blocklist in the stickapps IM. Return a list of blocked users for a given user here.

Arguments

• op = “get_blocklist”
• user_id - The user-id of the blocked list - “owner”

Return

list of blocked users separated by line delimiters as csv formated: user_id and name

Example

"user1","Justus Jonas"
"user2","Peter Shaw"

Called URL e.g.: your-domain.com/stickapps_api.php?op=get_blocklist&app_id=1&user_id=micha

Called when a user adds someone to the blacklist.

Arguments

• op = “set_blocked”
• from_user_id - id of user to add to blocked list
• to_user_id - the id of the user who is the “owner” of the blocked list

Return

• 1 - on success
• 0 - otherwise

Example

1

Called URL e.g.: your-domain.com/stickapps_api.php?op=set_blocked&app_id=1&to_user_id=micha&from_user_id=hans

Called when a users deletes someone from the blacklist.

Arguments

• op = “unset_blocked”
• from_user_id - id of user to delete from blocked list
• to_user_id - the id of the user who is the “owner” of the blocked list

Return

• 1 - on success
• 0 - otherwise

Example

1

Called URL e.g.: your-domain.com/stickapps_api.php?op=unset_blocked&app_id=1&to_user_id=micha&from_user_id=hans

Called when the user retrieves the friends list in the IM. You should return the users friend list here.

Arguments

• op = “get_friends”
• user_id - id of user who is the “owner” of the friends-list

Return

list of user_ids and user names separated by line delimiters

Example

"user1","Peter Shaw"
"user2","Bob Andrews"

Called URL e.g.: your-domain.com/stickapps_api.php?op=get_friends&app_id=1&user_id=micha

Called when a user adds someone to the friends list.

Arguments

• op = “set_friend”
• user_id - the id of the user who is the “owner” of the friends-list
• param1 - id of user to add to friends-list

Return

• 1 - on success
• 0 - otherwise

Example

1

Called URL e.g.: your-domain.com/stickapps_api.php?op=set_friend&app_id=1&user_id=micha&param1=hans

Called when a users deletes someone from the friends list.

Arguments

• op = “unset_friend”
• user_id - the id of the user who is the “owner” of the friends-list
• param1 - id of user who shall be deleted from friends-list

Return

• 1 - on success
• 0 - otherwise

Example

1

Called URL e.g.: your-domain.com/stickapps_api.php?op=unset_friend&app_id=1&user_id=micha&param1=hans

Called when a user users the advanced search in the Instant Messenger or the search filters (e.g. search by age, search by gender) in the Chatbar. You sould return the search results based on the given arguments here.

Arguments

• op = “search”
• name (optional) - the id of the user who is the “owner” of the friends-list
• gender (char, optional) - the gender of the user: either w = “female” or m = “male”
• from_age (integer, optional) - the minimum age (years) of a user
• to_age (integer, optional) - the maximum age (years) of a user
• city (string, optional) - the city of a user
• country (string, optional) - the country of a user

Return

list of search result separated by linebreaks each line is a comma separated list of values for user_id, name, gender, age, city, country enclosed by quotation marks

Example

"micha","Michael Glöß","m","29","Berlin","Germany"
"mike","Michael Jordan","m","45","New York","USA"

Called URL e.g.: your-domain.com/stickapps_api.php?op=search&app_id=1&name=Micha&gender=m&age=25-35

This is called when a user reports an abuse of another user in a chat.

Arguments

• op = “report_abuse”
• user_id - the ID of the user who reported the abuse
• param1 - the ID of the abuser
• param2 - a message of the abused user which describes the incident
• param3 - a part of the chat transcript
• city (string, optional) - the city of a user
• country (string, optional) - the country of a user

Return

• 1 - on success
• 0 - otherwise

Example

1

Called URL e.g.: your-domain.com/stickapps_api.php?op=report_abuse&app_id=1&user_id=micha&abuse_id=hans&msg=i+was+deeply+insulted&log=hans%3Ayour+are+really+a+%2A%2A%2A