-
Notifications
You must be signed in to change notification settings - Fork 5
[WIP] API for app to app communication
Note: Relevant discussion in https://github.com/kontalk/androidclient/issues/744
This page describes the desired API. It is still an early work in progress and will change through time.
The API is based on JSON-RPC 2.0 and follows that specification.
Get the API version used.
Example request:
{
"jsonrpc": "2.0",
"method": "version",
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": 1,
"id": 1
}
Get a list of all contacts.
Example request:
{
"jsonrpc": "2.0",
"method": "contacts"
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": [{
"id": "johndoe@beta.kontalk.net"
}, {
"id": "foobar@beta.kontalk.net"
}],
"id": 1
}
Get information of a single contact. When no id is passed, get information on yourself.
Example request:
{
"jsonrpc": "2.0",
"method": "contact",
"params": {
"id": "johndoe@beta.kontalk.net"
},
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": {
"name": "John Doe",
"status": "The name is Doe. John, Doe.",
"picture": <base64-encoded image>,
"lastActivity": 0
},
"id": 1
}
Update data of a contact. When no id is passed, update your own information.
Example request:
{
"jsonrpc": "2.0",
"method": "update-contact",
"params": {
"id": "johndoe@beta.kontalk.net",
"name": "John not so Doe."
},
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": null,
"id": 1
}
Block a contact.
Example request:
{
"jsonrpc": "2.0",
"method": "block-contact",
"params": {
"id": "johndoe@beta.kontalk.net",
},
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": null,
"id": 1
}
Delete a contact.
Example request:
{
"jsonrpc": "2.0",
"method": "delete-contact",
"params": {
"id": "johndoe@beta.kontalk.net",
},
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": null,
"id": 1
}
Get a list of all conversations.
Example request:
{
"jsonrpc": "2.0",
"method": "conversations"
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": [{
"id": "johndoe@beta.kontalk.net"
}, {
"id": "kittenloversanonymous@muc.beta.kontalk.net"
}],
"id": 1
}
Get all info of a single conversation.
The list of messages is limited to the last 25(?) messages. This should allow the user to have a basic idea of what the conversation was about, without allowing a malicious web client to extract the whole conversation history.
Example request:
{
"jsonrpc": "2.0",
"method": "conversation",
"params": {
"id": "kittenloversanonymous@muc.beta.kontalk.net"
},
"id": 1
}
Example response:
{
"jsonrpc": "2.0",
"result": {
"id": "kittenloversanonymous@muc.beta.kontalk.net",
"name": "Kitten Lovers Anonymous",
"type": "group",
"picture": <base64-encoded image>,
"participants": [{
"id": "johndoe@beta.kontalk.net",
"role": "member"
}, {
"id": "foobar@beta.kontalk.net",
"role": "admin"
}],
"messages": [{
"from": "foobar@beta.kontalk.net",
"type": "text/plain",
"sent": 1464386320,
"received": 1464386320,
"content": "Welcome to my group!"
}, {
"from": "foobar@beta.kontalk.net",
"type": "image/jpeg",
"sent": 14643863222,
"received": 1464386323,
"content": <base64-encoded image>
}, {
"from": "johndoe@beta.kontalk.net",
"type": "text/plain",
"sent": 1464386340,
"content": "Thanks!"
}]
}
}
Leave a conversation. Only usable in group chats. In single chats, returns an error.
Example request:
{
"jsonrpc": "2.0",
"method": "leave-conversation",
"params": {
"id": "kittenloversanonymous@muc.beta.kontalk.net"
}
}
Example response:
{
"jsonrpc": "2.0",
"result": null,
"id": 1
}
Remove a conversation. In a single conversation, this is equivalent to pressing "Delete chat" on the Android client. In a group conversation, this leaves and deletes the chat.
Example request:
{
"jsonrpc": "2.0",
"method": "remove-conversation",
"params": {
"id": "kittenloversanonymous@muc.beta.kontalk.net"
}
}
Example response:
{
"jsonrpc": "2.0",
"result": null,
"id": 1
}
Send a chat message.
The message id (returned by the server in result) is an unique id for each message. If a message with this id already exists, the received fields need to be updated. The message id should not be confused by the id given as part of identifying the specific jsonrpc request.
Example request:
{
"jsonrpc": "2.0",
"method": "message",
"params": {
"to": "kittenloversanonymous@muc.beta.kontalk.net",
"from": "me@beta.kontalk.net",
"type": "text/plain",
"pending": 1464439720,
"content": "That's a cute picture"
},
"id": 1
}
Example response upon successful sent:
{
"jsonrpc": "2.0",
"result": {
"id": 1,
"pending": null,
"sent": 1464439721
},
"id": 1
}
Remove a message.
Example request:
"jsonrpc": "2.0",
"method": "remove-message",
"params": {
"id": 1
},
"id": 1
Example response:
{
"jsonrpc": "2.0",
"result": null,
"id": 1
}
TODO: Properly document notifications, figure out how much is not obvious Example notification:
{
"jsonrpc": "2.0",
"method": "message",
"params": {
"id": 1,
"to": "me@beta.kontalk.net",
"from": "kittenloversanonymous@muc.beta.kontalk.net",
"type": "text/plain",
"received": 1464439721,
"content": "Absolutely definitely!"
},
"id": null
}