[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.

General notes

The API is based on JSON-RPC 2.0 and follows that specification.

Methods

version

Get the API version used.

Example request:

{
    "jsonrpc": "2.0",
    "method": "version",
    "id": 1
}

Example response:

{
    "jsonrpc": "2.0",
    "result": 1,
    "id": 1
}

contacts

Get a list of all contacts.

Example request:

{
    "jsonrpc": "2.0",
    "method": "contacts"
    "id": 1
}

Example response:

{
    "jsonrpc": "2.0",
    "result": [{
        "id": "[email protected]"
    }, {
        "id": "[email protected]"
    }],
    "id": 1
}

contact

Get information of a single contact. When no id is passed, get information on yourself.

Example request:

{
    "jsonrpc": "2.0",
    "method": "contact",
    "params": {
        "id": "[email protected]"
    },
    "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-contact

Update data of a contact. When no id is passed, update your own information.

Example request:

{
    "jsonrpc": "2.0",
    "method": "update-contact",
    "params": {
        "id": "[email protected]",
        "name": "John not so Doe."
    },
    "id": 1
}

Example response:

{
    "jsonrpc": "2.0",
    "result": null,
    "id": 1
}

block-contact

Block a contact.

Example request:

{
    "jsonrpc": "2.0",
    "method": "block-contact",
    "params": {
        "id": "[email protected]",
    },
    "id": 1
}

Example response:

{
    "jsonrpc": "2.0",
    "result": null,
    "id": 1
}

delete-contact

Delete a contact.

Example request:

{
    "jsonrpc": "2.0",
    "method": "delete-contact",
    "params": {
        "id": "[email protected]",
    },
    "id": 1
}

Example response:

{
    "jsonrpc": "2.0",
    "result": null,
    "id": 1
}

conversations

Get a list of all conversations.

Example request:

{
    "jsonrpc": "2.0",
    "method": "conversations"
    "id": 1
}

Example response:

{
    "jsonrpc": "2.0",
    "result": [{
        "id": "[email protected]"
    }, {
        "id": "[email protected]"
    }],
    "id": 1
}

conversation

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": "[email protected]"
    },
    "id": 1
}

Example response:

{
    "jsonrpc": "2.0",
    "result": {
        "id": "[email protected]",
        "name": "Kitten Lovers Anonymous",
        "type": "group",
        "picture": <base64-encoded image>,
        "participants": [{
            "id": "[email protected]",
            "role": "member"
        }, {
            "id": "[email protected]",
            "role": "admin"
        }],
        "messages": [{
            "from": "[email protected]",
            "type": "text/plain",
            "sent": 1464386320,
            "received": 1464386320,
            "content": "Welcome to my group!"
        }, {
            "from": "[email protected]",
            "type": "image/jpeg",
            "sent": 14643863222,
            "received": 1464386323,
            "content": <base64-encoded image>
        }, {
            "from": "[email protected]",
            "type": "text/plain",
            "sent": 1464386340,
            "content": "Thanks!"
        }]
    }
}

leave-conversation

Leave a conversation. Only usable in group chats. In single chats, returns an error.

Example request:

{
    "jsonrpc": "2.0",
    "method": "leave-conversation",
    "params": {
        "id": "[email protected]"
    }
}

Example response:

{
    "jsonrpc": "2.0",
    "result": null,
    "id": 1
}

remove-conversation

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": "[email protected]"
    }
}

Example response:

{
    "jsonrpc": "2.0",
    "result": null,
    "id": 1
}

message

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": "[email protected]",
        "from": "[email protected]",
        "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-message

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
}

Notifications

TODO: Properly document notifications, figure out how much is not obvious Example notification:

{
    "jsonrpc": "2.0",
    "method": "message",
    "params": {
        "id": 1,
        "to": "[email protected]",
        "from": "[email protected]",
        "type": "text/plain",
        "received": 1464439721,
        "content": "Absolutely definitely!"
    },
    "id": null
}