KOOK Developer Documentation

Roles are ordered from top to bottom; this order determines their priority (the position field).

Hierarchy Rules:

• Even with Administrator permissions, you can only manage users or roles with a lower priority than your own.
• You cannot manage, edit, or grant permissions to users or roles that have a priority equal to or higher than yours.

When using APIs to grant or update permissions, ensure the performing entity (e.g., a bot) has a higher position than the target role/user, otherwise the operation will fail.

KOOK imposes usage limits on the API, which may include:

• The number of API requests sent within a specific time unit.
• The number of servers a bot can reside in.
• The number of users a bot can serve.

If you require access to APIs that exceed these limits, you must obtain written authorization from KOOK.

Permissions are represented as an unsigned int value where each bit corresponds to a specific permission. To determine if a user or entity possesses a specific permission, perform a bitwise AND operation between the total permissions value and the bitmask of the target permission.

To check if a permission is present, use the following logic: permissions & (1 << bitValue) == (1 << bitValue)

// permissions: the total permission value
// bitValue: the index of the specific permission bit
// 1 << bitValue: the bitmask for that permission

if (permissions & (1 << bitValue) == (1 << bitValue)) {
    // User has the permission
}

The KOOK API is composed of two core layers that allow you to build bots or services:

1. Standard HTTP Interfaces: Used for performing regular operations (GET/POST requests).
2. Real-time Message Notifications: Used to subscribe to system messages and events via Webhook or Websocket.

Both layers follow consistent specifications for message meaning and structure, though message pushes may use zlib (deflate) compression.

Card messages are structured, JSON-based messages that provide a rich, interactive UI. A card message consists of a collection of card objects.

Structure Hierarchy:

• Card (card): The top-level container. A single message can contain up to 5 cards.
• Modules: Contained within a card (e.g., section, header, context). A single message cannot exceed 50 modules in total.
• Elements: Contained within modules (e.g., plain-text, image, button).
• Fields: Contained within structural components (e.g., paragraph).

General Object Schema: All elements follow a similar pattern:

{
    "type": "category",
    "foo": "bar",
    "modules|elements|fields": []
}

[
  {
    "type": "card",
    "modules": [
      // ...
    ]
  }
]

To prevent message loss during a disconnection, you can perform a session resumption. This requires appending specific parameters to the Gateway URL:

• resume: Set to 1.
• sn: The sequence number (sn) of the last successfully processed message. If no messages were received, use 0. You should persist this value (e.g., to a file) to allow recovery after a process restart.
• session_id: The session_id obtained from the initial HELLO packet.

Example URL structure: wss://[gateway_url]?resume=1&sn=[last_sn]&session_id=[session_id]

wss://test.kookapp.com:8888/gateway?{compress/token parameters}&resume=1&sn=5&session_id=20****ae-1fa4-4d19-805f-6f0f****d534

Authentication is performed by including a token in the Authorization HTTP header. The format is Authorization: <TOKEN_TYPE> <TOKEN>.

Supported types:

• Bot: Use Bot as the TOKEN_TYPE for bot-related operations.
• OAuth2: Use Bearer as the TOKEN_TYPE for OAuth2 flows.

Authorization: Bot BHsTZ4232tLatgV5AFyjoqZGAHHmpl9mTxYQ/u4/480=