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:

Variable	Description	Allowed Value
version	Version of the used API.	v1
app_source	Which app is used to connect to the server. Use “custom” if not in the list.	obs, streamerbot, custom
channel_id	The unique numeric identifier of the channel.	any

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
To Client

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
                        event_display_name:
                            type: string
                        product_sku:
                            type: string
                    required:
                        - event_id

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"
            }
        ]
    }
}

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

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
            event_display_name:
                type: string
            product_sku:
                type: string
            product_bits:
                type: number
            user_id:
                type: string
            user_display_name:
                type: string
        required:
            - event_id

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"
    }
}

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

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

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

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

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

Example payload (JSON):

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

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

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

Example payload (JSON):

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

request_event_list

This operation is sent to the server.

Send this to receive a list of current events.

AsyncApi schema for message:

type: object
properties:
    type:
        type: string
        const: request_event_list
    data:
        type: object
        properties:
            secret:
                type: string

Example payload (JSON):

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

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
                        event_display_name:
                            type: string
                        product_sku:
                            type: string
                    required:
                        - event_id
        required:
            - events

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"
            }
        ]
    }
}

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

Example payload (JSON):

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

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

Example payload (JSON):

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