API Calls

For all calls to this api, session cookie is used and have a timeout of xxx seconds.
Dont' forget to url_encode all the parameters of your calls

*** Registration / Authentication ***

/create_account

Description
Register a new user on kraml.
URL Structure
https://api.kraml.fr/create_account
Method
POST
Parameter
user => Mandatory - The username
password => Mandatory - The password

/connect

Description
Connect a user to kraml.
URL Structure
https://api.kraml.fr/connect
Method
POST
Parameter
user => Mandatory - The username
password => Not Mandatory - The password (if not set, consider anonymous connection)
Notes
Don't forget to set status to become Online.

/disconnect

Description
Disconnect a user from kraml.
URL Structure
https://api.kraml.fr/disconnect
Method
POST
Notes
After this call authentificated commands will not work.

*** Account Management ***

/status

Description
Change current status of user.
URL Structure
https://api.kraml.fr/status
Method
POST
Parameter
age => Not Mandatory - The age of ASL
sex => Not Mandatory - The sex of ASL
location => Not Mandatory - The location of ASL
show => Not Mandatory - New status, can be : chat / dnd / ... (default to chat)
status => Not Mandatory - Message of status (what you want)

/add_friend

Description
Request another user to become your friend, or accept his request
URL Structure
https://api.kraml.fr/add_friend
Method
POST
Parameter
user => Mandatory - The other user

/delete_friend

Description
Delete a friend from tour friendlist, or decline a request
URL Structure
https://api.kraml.fr/delete_friend
Method
POST
Parameter
user => Mandatory - The other user

*** Chat Commands ***

/ping

Description
Must be called after the login process, return the data
URL Structure
https://api.kraml.fr/ping
Method
POST
Notes
This call has a 30 seconds timeout, after what you have to ping again, show examples for more details.

/join

Description
Join a room, and leave old room if necessary
URL Structure
https://api.kraml.fr/join
Method
POST
Parameter
room_name => Mandatory - The room Name
room_lang => Mandatory - The room Lang (fr/en/...)

/room_message

Description
Send a message to the current room
URL Structure
https://api.kraml.fr/room_message
Method
POST
Parameter
text => Mandatory - The message

/private_message

Description
Send a private message to a user
URL Structure
https://api.kraml.fr/pv_message
Method
POST
Parameter
user => Mandatory - The recipient of the message
message => Mandatory - The message

*** Utility Commands ***

/connected_users

Description
Get all the connected_users, with the given filter
URL Structure
https://api.kraml.fr/connected_users
Method
POST
Parameter
agefrom => Not Mandatory - Filter on min age
ageto => Not Mandatory - Filter on max age
sex => Not Mandatory - Filter on sex
location => Not Mandatory - Filter on location
name ?? => A filter on user name
limit => Not Mandatory - Number of results per page (default to 25)
first => Not Mandatory - Use first=26 to have records 26 to 0 (default to 0)
order => Not Mandatory - Define results order like that : sex,age,location - (default to age,sex,location)

/friends

Description
Get friends of the currently connected user
URL Structure
https://api.kraml.fr/friends
Method
POST

/rooms

Description
Get the rooms currently active on kraml
URL Structure
https://api.kraml.fr/rooms
Method
POST
Parameter
name ?? => A filter on room name
limit => Not Mandatory - Number of results per page (default to 25)
first => Not Mandatory - Use first=26 to have records 26 to 0 (default to 0)

/infos

Description
Get info of a kraml service
URL Structure
https://api.kraml.fr/infos
Method
POST
Parameter
service => Mandatory - The service

/room_users

Description
Get info of room occupants
URL Structure
https://api.kraml.fr/room_users
Method
POST
Parameter
room => Mandatory - The room ID

/get_available_languages

Description
Get all the available languages
URL Structure
https://api.kraml.fr/get_available_languages
Method
POST

/picture

Description
Get picture of given user
URL Structure
https://api.kraml.fr/picture
Method
POST
Parameter
user => Mandatory - The user we want the picture
size => large or small (default to large)
method => redirect (302 redirect to the url), url (json response), base64 (json response) -- (default to redirect)

Returns

All returns are in json. A return is a list of 'response' object : 
[
    {"response": ...
    },
    {"response": ...
    }
]
Each response have a type, and some data depending of the type.
Each asynchronous response have a reping value, if set to true, you have to call a /ping command again.

*** Registration / Authentication ***

connected

Description
Response on successful authentication
Response Structure
{
    "response":"conected",
    "username":"<username>",
    "anonymous":true,
    "reping":false,
}

- with <username> the effective user connected on kraml

authentication_failed

Description
Response on unsuccessful authentication
Response Structure
{
    "response":"authentication_failed",
    "reason":"anonymous_user_already_connected",
    "reping":false
}

- Give you the reason why rejected

userCreated

Description
After registration, result successful
Response Structure
{
    "response":"userCreated",
    "message":"MSG account_created_successfully"
}

disconnected

Description
You have been disconnected. Can occur if error, or if you have called the disconnect command.
Response Structure
{
    "response":"disconnected",
    "reping":false
}

*** Account Management ***

presence / status change

Description
Response on presence(s) received
Response Structure
{
    "response":"presence",
    "presences":[
        {
            "type":"status_change",
            "from":"temp_user_test",
            "show":"chat",
            "status":"apiTest",
            "age":"0",
            "sex":"",
            "location":""
        }
    ],
    "reping":false
}

presence / room change

Description
Response on room change
Response Structure
{
    "response":"presence",
    "presences":[
        {
            "type":"room_change",
            "from":"temp_user_test",
            "show":"chat",
            "status":"apiTest",
            "age":"0",
            "sex":"",
            "location":""
        }
    ],
    "reping":false
}

friend_accepted

Description
When you accept a friend request
Response Structure
{
    "response":"friend_accepted",
    "reping":false
}

*** Chat Returns ***

pinged

Description
Response on an empty ping result (no new data received before timeout - 30s)
Response Structure
{
    "response":"pinged",
    "body":"[..some data..]",
    "reping":true
}

message / groupchat

Description
Response on groupchat (room) message received
Response Structure
{
    "response":"message",
    "messages":[
        {
            "type":"groupchat",
            "from":"temp_user_1",
            "to":"temp_user_2",
            "text":"My message"
        }
    ]
}

message_sent

Description
Response when you send a private message
Response Structure
{
    "response":"message_sent",
    "body":"Hi Man",
    "reping":false
}

*** Utility ***

search

Description
Response on a search command
Response Structure
{
    "response":"search_results",
    "results":[
        {
            "user":"monuser",
            "age":"22",
            "sex":"M",
            "location":"My City",
            "show":"chat"
        },{
            "user":"user2",
            "age":"26",
            "sex":"F",
            "location":"Sexy town",
            "show":"dnd"
        }
    ],
    "paging": {
        "previous":"0",
        "next":"25"
    }
}

picture

Description
Response on a url-method for picture
Response Structure
{
    "response":"picture",
    "mode":"url",
    "reping":false,
    "data":"http:\/\/kraml.fr\/v2\/pictures\/default.jpg"
}

*** Errors ***

error

Description
Response when error occured
Response Structure
{
    "response":"error",
    "error_code":"3",
    "error_message":"not_connected",
    "reping":false
}

- Here example calling the ping command without authenticate

ping_error

Description
Response when error occured in ping command
Response Structure
{
    "response":"ping_error",
    "request":"[..some data..]",
    "reping":true
}