-
Notifications
You must be signed in to change notification settings - Fork 5
API
Kira allows applications to connect directly to it to receive real time updates. This is always based on a single users authentication and the information provided is limited to the one the user has access to.
To obtain an API token, run the command apitoken in Discord. It will generate a token, which gives API access to all snitch alerts and group chat messages of all your groups. Tokens are one time use only and expire after five minutes if not used.
Kira has an open web socket at mc.civclassic.com on port 14314. You are expected to provide the following as URL parameters:
apiToken is the token you previously obtained from Kira on Discord
applicationId is an identifier unique to your application. It should stay the same for the same application across all users, but may include version information and change with version changes of the application.
apiVersion should always be the value specified here, at the moment 1. It may be used to reject clients expecting an outdated version of the protocol.
Example URL: wss://mc.civclassic.com:14314?apiToken=wdfhehscjgbneux&applicationId=maxopoly-website&apiVersion=1
Note that parameter keys are case sensitive as per RFC 3986.
All packets sent by and to Kira are JSON. They all have a field called type which specifies their particular purpose.
The following is a list of all packets Kira can send to you
Sent if the API token provided during authentication is not valid. Kira will close the connection immediately after sending this packet
{
"type": "auth",
"valid": false
}
If the API token provided during authentication is valid, this will be the first packet Kira responds with. It will only be sent once per session.
{
"type": "auth",
"valid": true,
"expires": 1553533645,
"chats": ["!", "Hjaltland", "Maxopoly"],
"snitches": ["Hjaltland", "Maxopoly"],
"skynet": true
}
expires is a UNIX time stamp indicating when the provided token will expire, at which point Kira will stop sending data. If the provided token does not expire, expires will be set to -1
chats is a JSON array containing the names of all groups Kira will send group messages for
snitches is a JSON array containing the names of all groups Kira will send snitch alerts for
skynet is a boolean value indicating whether skynet messages and new player announcements will be sent
Sent either in reply to explicitly requesting a new token (with this packet) or when the server shuts down. The received token can be used to reconnect after the connection has been interrupted and will retain all permissions and configurations of the current session upon reconnecting.
{
"type": "new-token",
"secret": "squidsAreReallyCoolAnimals",
"expires": 1349333576093
}
secret is the API token which can be used for reconnecting
expires is a UNIX time stamp indicating when the provided token will expire, at which point Kira will stop sending data. If the provided token does not expire, expires will be set to -1
Sent as a response to running a command using this packet
{
"type": "ingame-response",
"identifier": "UNIQUE_IDENTIFIER",
"response": "§aThe invitation has been sent."
}
identifier is a unique identifying string which is used to identify which command the reponse is about.
response is a string representing the response to a command with the matching identifer.
There is only one message format for providing data:
{
"type": "data",
"group-messages": [...],
"snitch-alerts": [...],
"skynet": [...],
"new-players": [...]
}
Each of the arrays contains JSON objects, which each describe one event. A JSON array may be missing entirely if no content is available for it. For example the skynet array will only be in the packet if the provided API token included skynet data and logins/logouts happened since the last update.
All event JSONs include a UNIX timestamp field
{
"time": 1553533645
}
Can only be found within the group-messages JSON array in a data packet and describes one group chat message
{
"time": 1553533645,
"group": "Hjaltland",
"player": "Frensin",
"message": "Hello"
}
group is the name of the group the message was sent to
player is the name of the player who sent the message
message is the message sent
Can only be found within the snitch-alerts JSON array in a data packet and describes one snitch alert
{
"time": 1553533645,
"player": "Frensin",
"action": "ENTER",
"snitch": {
"location": {
"x": 1000,
"y": 64,
"z": 1000,
"world": "world_the_end"
},
"name": "SecretBase",
"group": "Hjaltland",
"type": "ENTRY"
}
}
location is the location of the snitch
group is the name of the group the snitch is broadcasting to
player is the name of the player who hit the snitch
name is the name of the snitch. May be an empty string if the snitch has no explicit name.
action is one of the following: ENTER, LOGIN or LOGOUT and describes what the player did to cause this alert
type is either LOGGING or ENTRY and describes the type of snitch
Can only be found within the skynet JSON array in a data packet and describes one skynet event
{
"time": 1553533645,
"player": "Frensin",
"action": "LOGIN"
}
player is the name of the player who logged in/out
action is either LOGIN or LOGOUT and describes what the player did
Can only be found within the new-players JSON array in a data packet and announces a new player logging in to the server for the first time.
{
"time": 1560123374,
"player": "Gjum"
}
player is the name of the player who logged in for the first time.
The following is a list of all packets you can send to Kira
Allows you to request a new token, which can be used to reconnect with the same permissions after restarting your client. In response to this the server will send this packet, flush out any remaining data and then close the connection.
{
"type": "new-token"
}
Allows you to run an in-game command as the current session user. In response to this the server will send this packet.
{
"type": "in-game",
"identifier": "UNIQUE_IDENTIFIER",
"command": "nlip SuperSecretSnitchGroup Mickale"
}