API

This document describes the APIs used for connecting any streaming client to the WebSocket server.

v1 OBS / Streamerbot / Custom

Server Information

To connect to a server, use the following url:

wss://streamsocket.kadokta.com/api/{version}/streamer/{app_source}/channel/{channel_id}

Replace each {variable} with the following:

Operations

The following operations with their corresponding messages should be managed by the client. WebSocket messages have a payload that include the type of the message and a data property (if required).

• To Server
  • notification_category_lock
  • notification_category_reset
  • notification_category_unlock
  • notification_config_reset
  • notification_event_lock
  • notification_event_reset
  • notification_event_unlock
  • notification_skip_queue
  • notification_status_change
  • request_category_list
  • request_config
  • request_event_list
  • request_secret_check
  • response_connection_check
  • response_event_data
• To Client
  • notification_config_update
  • notification_error
  • notification_event
  • request_connection_check
  • request_event_data

notification_category_lock

This operation is sent to the server.

Locks categories according to their category_id.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_category_lock
    data:
        type: object
        properties:
            secret:
                type: string
            categories:
                description: List of category ids
                type: array
                items:
                    type: string
        required:
            - secret
            - categories
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_category_lock",
    "data": {
        "secret": "example_secret",
        "categories": ["example", "example2"]
    }
}

notification_category_reset

This operation is sent to the server.

Resets the locks of the category to their default.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_category_reset
    data:
        type: object
        properties:
            secret:
                type: string
            categories:
                description: Array of category ids to reset
                type: array
                items:
                    type: string
            all:
                description: Whether to reset all categories (overrides 'categories' property if
                    present)
                type: boolean
                default: false
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_category_reset",
    "data": {
        "secret": "example_secret",
        "categories": ["example", "example2"]
    }
}

notification_category_unlock

This operation is sent to the server.

Unlocks categories according to their category_id.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_category_unlock
    data:
        type: object
        properties:
            secret:
                type: string
            categories:
                description: List of category ids
                type: array
                items:
                    type: string
        required:
            - secret
            - categories
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_category_unlock",
    "data": {
        "secret": "example_secret",
        "categories": ["example", "example2"]
    }
}

notification_config_reset

This operation is sent to the server.

Resets the locks and limits of everything.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_config_reset
required:
    - type

Example payload (JSON):

{
    "type": "notification_config_reset"
}

notification_config_update

This operation is received by the client.

Received by the client if the config was updated.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_config_update
    data:
        type: object
        properties:
            time:
                type: number
                description: Date the config was updated (number of milliseconds elapsed since
                    epoch)
            events:
                description: List of events
                type: array
                items:
                    type: object
                    properties:
                        event_id:
                            type: string
                            pattern: ^[\d\w\-_]+$
                            maxLength: 32
                        event_display_name:
                            type: string
                        product_sku:
                            type: string
                        categories:
                            type: array
                            items:
                                type: string
                    required:
                        - event_id
        required:
            - time
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_config_update",
    "data": {
        "time": 100,
        "events": [
            {
                "event_id": "example_event_id",
                "event_display_name": "example_event_display_name",
                "product_sku": "example_product_sku",
                "categories": ["example", "example2"]
            }
        ]
    }
}

notification_error

This operation is received by the client.

When a message caused an error (e.g. invalid secret).

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_error
    data:
        type: object
        properties:
            error_name:
                enum:
                    - unknown
                    - invalid_secret
            error_message:
                type: string
        required:
            - error_name
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_error",
    "data": {
        "error_name": "unknown",
        "error_message": "example_error_message"
    }
}

notification_event

This operation is received by the client.

When an event is redeemed (either by a viewer or as a test by the streamer).

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_event
    data:
        type: object
        properties:
            event_id:
                type: string
                pattern: ^[\d\w\-_]+$
                maxLength: 32
            event_display_name:
                type: string
            product_sku:
                type: string
            product_bits:
                type: number
            user_id:
                type: string
            user_display_name:
                type: string
            is_test:
                type: boolean
            category_ids:
                type: array
                items:
                    type: string
                    pattern: ^[\d\w\-_]+$
                    maxLength: 32
        required:
            - event_id
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_event",
    "data": {
        "event_id": "example_event_id",
        "event_display_name": "example_event_display_name",
        "product_sku": "example_product_sku",
        "product_bits": 100,
        "user_id": "example_user_id",
        "user_display_name": "example_user_display_name",
        "is_test": true,
        "category_ids": ["example", "example2"]
    }
}

notification_event_lock

This operation is sent to the server.

Locks events according to their event_id.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_event_lock
    data:
        type: object
        properties:
            secret:
                type: string
            events:
                description: List of event ids
                type: array
                items:
                    type: string
        required:
            - secret
            - events
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_event_lock",
    "data": {
        "secret": "example_secret",
        "events": ["example", "example2"]
    }
}

notification_event_reset

This operation is sent to the server.

Resets the locks and limits of the event to their default.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_event_reset
    data:
        type: object
        properties:
            secret:
                type: string
            events:
                description: Array of event ids to reset
                type: array
                items:
                    type: string
            all:
                description: Whether to reset all events (overrides 'events' property if present)
                type: boolean
                default: false
        required:
            - secret
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_event_reset",
    "data": {
        "secret": "example_secret",
        "events": ["example", "example2"]
    }
}

notification_event_unlock

This operation is sent to the server.

Unlocks events according to their event_id.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_event_unlock
    data:
        type: object
        properties:
            secret:
                type: string
            events:
                description: List of event ids
                type: array
                items:
                    type: string
        required:
            - secret
            - events
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_event_unlock",
    "data": {
        "secret": "example_secret",
        "events": ["example", "example2"]
    }
}

notification_skip_queue

This operation is sent to the server.

Used to skip queues, i.e. to immediately make other events redeemable again after an event with a set duration has been sent.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_skip_queue
    data:
        type: object
        properties:
            secret:
                type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_skip_queue",
    "data": {
        "secret": "example_secret"
    }
}

notification_status_change

This operation is sent to the server.

Used to enable or disable sending of events by viewers.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: notification_status_change
    data:
        type: object
        properties:
            secret:
                type: string
            active:
                type: boolean
        required:
            - secret
            - active
required:
    - type
    - data

Example payload (JSON):

{
    "type": "notification_status_change",
    "data": {
        "secret": "example_secret",
        "active": true
    }
}

request_category_list

This operation is sent to the server.

Send this to receive a list of categories.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_category_list
    data:
        type: object
        properties:
            secret:
                type: string
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "request_category_list",
    "data": {
        "secret": "example_secret"
    },
    "request_id": "example_request_id"
}

On receiving a valid message, the server sends a reply:

• response_category_list

response_category_list

Reply to request_category_list

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: response_category_list
    data:
        type: object
        properties:
            categories:
                description: List of categories
                type: array
                items:
                    type: object
                    properties:
                        category_ids:
                            type: string
                            pattern: ^[\d\w\-_]+$
                            maxLength: 32
                        category_display_name:
                            type: string
                        events:
                            type: array
                            items:
                                type: string
        required:
            - categories
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "response_category_list",
    "data": {
        "categories": [
            {
                "category_ids": "example_category_ids",
                "category_display_name": "example_category_display_name",
                "events": ["example", "example2"]
            }
        ]
    },
    "request_id": "example_request_id"
}

request_config

This operation is sent to the server.

Send this to receive config information, including events and categories.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_config_save
    data:
        type: object
        properties:
            secret:
                type: string
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "request_config_save",
    "data": {
        "secret": "example_secret"
    },
    "request_id": "example_request_id"
}

On receiving a valid message, the server sends a reply:

• response_config

response_config

Reply to request_config

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_config_save
    data:
        type: object
        properties:
            events:
                description: List of events
                type: array
                items:
                    type: object
                    properties:
                        event_id:
                            type: string
                            pattern: ^[\d\w\-_]+$
                            maxLength: 32
                        event_display_name:
                            type: string
                        product_sku:
                            type: string
                        categories:
                            type: array
                            items:
                                type: string
                    required:
                        - event_id
            categories:
                description: List of categories
                type: array
                items:
                    type: object
                    properties:
                        category_ids:
                            type: string
                            pattern: ^[\d\w\-_]+$
                            maxLength: 32
                        category_display_name:
                            type: string
                        events:
                            type: array
                            items:
                                type: string
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "request_config_save",
    "data": {
        "events": [
            {
                "event_id": "example_event_id",
                "event_display_name": "example_event_display_name",
                "product_sku": "example_product_sku",
                "categories": ["example", "example2"]
            }
        ],
        "categories": [
            {
                "category_ids": "example_category_ids",
                "category_display_name": "example_category_display_name",
                "events": ["example", "example2"]
            }
        ]
    },
    "request_id": "example_request_id"
}

request_connection_check

This operation is received by the client.

A check used by the server to test whether the client is connected (similar to a ping). The reply includes information about the current status (whether the viewers can send events) and the secret.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_connection_check
required:
    - type

Example payload (JSON):

{
    "type": "request_connection_check"
}

This message requires a reply to be sent to the server:

• response_connection_check

response_connection_check

Reply to request_connection_check

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: response_connection_check
    data:
        type: object
        properties:
            secret:
                type: string
            active:
                type: boolean
        required:
            - secret
            - active
required:
    - type
    - data

Example payload (JSON):

{
    "type": "response_connection_check",
    "data": {
        "secret": "example_secret",
        "active": true
    }
}

request_event_data

This operation is received by the client.

This is sent by the server if custom response is active for an event. Requires a response with the corresponding request_id.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_event_data
    data:
        type: object
        properties:
            event_id:
                type: string
                pattern: ^[\d\w\-_]+$
                maxLength: 32
            event_display_name:
                type: string
            product_sku:
                type: string
            product_bits:
                type: number
            user_id:
                type: string
            user_display_name:
                type: string
            is_test:
                type: boolean
            category_ids:
                type: array
                items:
                    type: string
                    pattern: ^[\d\w\-_]+$
                    maxLength: 32
        required:
            - event_id
    request_id:
        type: string
required:
    - type
    - data
    - request_id

Example payload (JSON):

{
    "type": "request_event_data",
    "data": {
        "event_id": "example_event_id",
        "event_display_name": "example_event_display_name",
        "product_sku": "example_product_sku",
        "product_bits": 100,
        "user_id": "example_user_id",
        "user_display_name": "example_user_display_name",
        "is_test": true,
        "category_ids": ["example", "example2"]
    },
    "request_id": "example_request_id"
}

This message requires a reply to be sent to the server:

• response_event_data

response_event_data

Reply to request_event_data

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: response_event_data
    data:
        type: object
        properties:
            data_type:
                enum:
                    - constant
            message:
                description: The message that is sent to the viewer, to be shown within the
                    extension. Supports simple markdown with ** (bold) and \n (line
                    break).
                type: string
            options:
                type: object
                properties:
                    write_chat:
                        description: Whether to write a chat message. Overrides event configuration.
                            Requires chat capabilities.
                        type: boolean
                    write_chat_message:
                        description: Custom chat message to use if one is written.
                        type: string
                        maxLength: 500
                    use_duration_global:
                        description: Global duration in ms to use. Overrides event configuration.
                        type: integer
                        minimum: 0
        required:
            - data_type
    request_id:
        type: string
required:
    - type
    - data
    - request_id

Example payload (JSON):

{
    "type": "response_event_data",
    "data": {
        "data_type": "constant",
        "message": "example_message",
        "options": {
            "write_chat": true,
            "write_chat_message": "example_write_chat_message"
        }
    },
    "request_id": "example_request_id"
}

request_event_list

This operation is sent to the server.

Send this to receive a list of events.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_event_list
    data:
        type: object
        properties:
            secret:
                type: string
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "request_event_list",
    "data": {
        "secret": "example_secret"
    },
    "request_id": "example_request_id"
}

On receiving a valid message, the server sends a reply:

• response_event_list

response_event_list

Reply to request_event_list

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: response_event_list
    data:
        type: object
        properties:
            events:
                description: List of events
                type: array
                items:
                    type: object
                    properties:
                        event_id:
                            type: string
                            pattern: ^[\d\w\-_]+$
                            maxLength: 32
                        event_display_name:
                            type: string
                        product_sku:
                            type: string
                        categories:
                            type: array
                            items:
                                type: string
                    required:
                        - event_id
        required:
            - events
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "response_event_list",
    "data": {
        "events": [
            {
                "event_id": "example_event_id",
                "event_display_name": "example_event_display_name",
                "product_sku": "example_product_sku",
                "categories": ["example", "example2"]
            }
        ]
    },
    "request_id": "example_request_id"
}

request_secret_check

This operation is sent to the server.

Send this to check whether a secret is valid.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_secret_check
    data:
        type: object
        properties:
            secret:
                type: string
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "request_secret_check",
    "data": {
        "secret": "example_secret"
    },
    "request_id": "example_request_id"
}

On receiving a valid message, the server sends a reply:

• response_secret_check

response_secret_check

Reply to request_secret_check

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: response_secret_check
    data:
        type: object
        properties:
            valid:
                type: boolean
    request_id:
        type: string
required:
    - type
    - data

Example payload (JSON):

{
    "type": "response_secret_check",
    "data": {
        "valid": true
    },
    "request_id": "example_request_id"
}