WebSocket API Reference

This document is a description of most of the APIs available for use in the PubSub WebSocket.

Table of Contents

WebSocket Events

Events take the form of...

interface Event {
  domain: string
  type: string
  payload: unknown
}

...where payload is defined in the following sections for each event.

`direct` domain

Events sent directly to a WebSocket connection. These are mostly responses to requests.

`subscription-result` type

Sent after you send a subscribe request.

Payload

interface DirectSubscriptionResultPayload {
  success: string[]
  failure: string[]
}

`whoami` type

Sent after you send a whoami request.

Payload

interface DirectWhoAmIPayload {
  connectionID: string
}

`login-success` type

Sent when a user uses the connectionID from the whoami event to log in to a Crowd Control account.

Payload

interface DirectLoginSuccessEvent {
  token: string // CrowdControlAuthToken
}

`login-failure` type

Sent when a user uses the connectionID from the whoami event to try logging into a Crowd Control account, but experiences an issue.

Payload

interface DirectLoginFailureEvent {
  title?: string
  message?: string
  link?: {
    href: string
    text: string
  }
}

`bad-request` type

Sent when you make an invalid request.

Payload

interface DirectBadRequestEvent {
  message: string
}

`game-session-checksum-update` type [direct]

Payload

interface DirectGameSessionChecksumUpdate {
  checksum: string
}

`pub` domain

Events intended to be received by any viewer of a Crowd Control streamer.

`game-session-start` type

Payload

interface PublicGameSessionStartPayload {
  gameSessionID: string // GameSessionID
}

`game-session-stop` type

Payload

interface PublicGameSessionStopPayload {
  gameSessionID: string // GameSessionID
}

`lobby-user-update` type

Payload

interface PublicLobbyUserUpdatePayload {
  participant: {
    // LobbyUser
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    status: 'in-session' | 'checklist-green' | 'checklist-red' | 'left' // LobbyStatus
    /**
     * When the user joined the lobby in ISO format
     */
    joinedAt: string
  }
}

`lobby-user-remove` type

Payload

interface PublicLobbyUserRemovePayload {
  ccUID: string // CrowdControlUserID
}

`effect-request` type [pub]

Payload

interface PublicEffectRequestPayload {
  effect: {
    // GameSessionPublicEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  origin?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  requester?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  sourceDetails?:
    | {
        // SanitizedSourceDetails
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`timed-effect-update` type [pub]

Payload

interface PublicTimedEffectUpdatePayload {
  status: 'begin' | 'end' | 'pause' | 'resume' // GameSessionTimedEffectStatus
  /**
   * Time remaining on the effect in milliseconds
   */
  timeRemaining: number
  effect: {
    // GameSessionPublicEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  origin?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  requester?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  sourceDetails?:
    | {
        // SanitizedSourceDetails
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-success` type [pub]

Payload

interface PublicEffectSuccessPayload {
  effect: {
    // GameSessionPublicEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  origin?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  requester?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  sourceDetails?:
    | {
        // SanitizedSourceDetails
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-refund` type [pub]

Payload

interface PublicEffectRefundPayload {
  effect: {
    // GameSessionPublicEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  origin?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  requester?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  sourceDetails?:
    | {
        // SanitizedSourceDetails
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-retry` type [pub]

Payload

interface PublicEffectRetryPayload {
  effect: {
    // GameSessionPublicEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  origin?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  requester?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  sourceDetails?:
    | {
        // SanitizedSourceDetails
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-failure` type [pub]

Payload

interface PublicEffectFailurePayload {
  temporary?: boolean
  message?: string
  effect: {
    // GameSessionPublicEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  origin?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  requester?: {
    // SanitizedUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
  }
  sourceDetails?:
    | {
        // SanitizedSourceDetails
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`game-session-menu-update` type

A partial update of the session's menu. Unchanged parameters or identified array entries may be missing.

Payload

interface PublicGameSessionMenuUpdatePayload {
  menu: {
    meta: {
      /**
       * The game that owns this game pack.
       * A game can hold multiple packs, for instance the "Super Mario 64" game contains
       * "Super Mario 64", "Super Mario 64 Randomizer v0.5.2", and "Super Mario 64 Randomizer v1.1.2".
       * The game is used for basic display in the game library while the pack determines the connector data and effect list.
       */
      game: {
        name:
          | string
          | {
              public: string
              sort?: string
            }
        gameID: string
        platforms: (
          | 'GB'
          | 'GBA'
          | 'GCN'
          | 'GEN'
          | 'GG'
          | 'IOT'
          | 'N64'
          | 'NES'
          | 'Other'
          | 'PC'
          | 'PS1'
          | 'PS2'
          | 'SNES'
          | 'Wii'
          | 'WiiU'
        )[]
        tags?: string[]
        title?: string
        description?: string
        image?: string
        twitch?: {
          id: string
        }
        keywords?: string[]
        recommended?: boolean
        releaseDate: string
        earlyAccess?: boolean
        newUpdate?: boolean
        disabled?: boolean
        clips?: {
          platform: string
          name: string
          url: string
        }[]
      }
      name:
        | string
        | {
            public: string
            sort?: string
          }
      description?: string
      image?: string
      recommended?: boolean
      releaseDate: string
      earlyAccess?: boolean
      newUpdate?: boolean
      disabled?: boolean
      note?: string
      new?: boolean
      emulator?: 'bizhawk' | 'cemu' | 'dolphin' | 'pcsx2' | 'project64'
      firmware?: string
      executable?: string
      initiateFromCrowdControl?: boolean
      launcher?: string
      process?: string
      mod?: {
        path?: string
        version?: string
        port?: number
        logPath?: string
      }
      extraArgs?: string[]
      patch?: boolean
      proExclusive?: boolean
      guide?: string
      guideCheck?: boolean
      thunderstore?: {
        name?: string
        url?: string
        handlerURL?: string
        modName?: string
        incompatibleMods?: string[]
      }
      warningMessage?: string
      supportedVersions?: {
        id: string
        rev: number
      }[]
      prelaunch?: boolean
      devs?: {
        name: string
        url?: string
      }[]
      frameworks?: {
        name: string
        id: string
      }[]
      lastStepMessage?: string
    }
    effects: {
      name:
        | string
        | {
            public: string
            sort?: string
          }
      effectID: EffectID
      type: 'game'
      tags?: string[]
      description?: string
      image?: string
      disabled?: boolean
      note?: string
      new?: boolean
      inactive?: boolean
      admin?: boolean
      category?: string[]
      group?: string[]
      tiktok?: {
        name: string
        image: string
        id: number
        duration?: {
          value: number
          immutable?: boolean
        }
      }
      sessionCooldown?: {
        startTime: number
        duration: number
      }
      userCooldown?: {
        startTime: number
        duration: number
      }
      scale?: {
        duration: number
        percent: number
        startTime: number
        startScale: number
      }
      hidden?: boolean
      unavailable?: boolean
    }[]
  }
}

`game-session-menu-sync` type

Like game-session-menu-sync, but it includes the full effects array.

Payload

interface PublicGameSessionMenuSyncPayload {
  menu: {
    meta: {
      /**
       * The game that owns this game pack.
       * A game can hold multiple packs, for instance the "Super Mario 64" game contains
       * "Super Mario 64", "Super Mario 64 Randomizer v0.5.2", and "Super Mario 64 Randomizer v1.1.2".
       * The game is used for basic display in the game library while the pack determines the connector data and effect list.
       */
      game: {
        name:
          | string
          | {
              public: string
              sort?: string
            }
        gameID: string
        platforms: (
          | 'GB'
          | 'GBA'
          | 'GCN'
          | 'GEN'
          | 'GG'
          | 'IOT'
          | 'N64'
          | 'NES'
          | 'Other'
          | 'PC'
          | 'PS1'
          | 'PS2'
          | 'SNES'
          | 'Wii'
          | 'WiiU'
        )[]
        tags?: string[]
        title?: string
        description?: string
        image?: string
        twitch?: {
          id: string
        }
        keywords?: string[]
        recommended?: boolean
        releaseDate: string
        earlyAccess?: boolean
        newUpdate?: boolean
        disabled?: boolean
        clips?: {
          platform: string
          name: string
          url: string
        }[]
      }
      name:
        | string
        | {
            public: string
            sort?: string
          }
      description?: string
      image?: string
      recommended?: boolean
      releaseDate: string
      earlyAccess?: boolean
      newUpdate?: boolean
      disabled?: boolean
      note?: string
      new?: boolean
      emulator?: 'bizhawk' | 'cemu' | 'dolphin' | 'pcsx2' | 'project64'
      firmware?: string
      executable?: string
      initiateFromCrowdControl?: boolean
      launcher?: string
      process?: string
      mod?: {
        path?: string
        version?: string
        port?: number
        logPath?: string
      }
      extraArgs?: string[]
      patch?: boolean
      proExclusive?: boolean
      guide?: string
      guideCheck?: boolean
      thunderstore?: {
        name?: string
        url?: string
        handlerURL?: string
        modName?: string
        incompatibleMods?: string[]
      }
      warningMessage?: string
      supportedVersions?: {
        id: string
        rev: number
      }[]
      prelaunch?: boolean
      devs?: {
        name: string
        url?: string
      }[]
      frameworks?: {
        name: string
        id: string
      }[]
      lastStepMessage?: string
    }
    effects: {
      name:
        | string
        | {
            public: string
            sort?: string
          }
      effectID: EffectID
      type: 'game'
      tags?: string[]
      description?: string
      image?: string
      disabled?: boolean
      note?: string
      new?: boolean
      inactive?: boolean
      admin?: boolean
      category?: string[]
      group?: string[]
      tiktok?: {
        name: string
        image: string
        id: number
        duration?: {
          value: number
          immutable?: boolean
        }
      }
      sessionCooldown?: {
        startTime: number
        duration: number
      }
      userCooldown?: {
        startTime: number
        duration: number
      }
      scale?: {
        duration: number
        percent: number
        startTime: number
        startScale: number
      }
      hidden?: boolean
      unavailable?: boolean
    }[]
  }
}

`pro-subscription-update` type

Payload

interface PublicProSubscriptionUpdatePayload {
  active: boolean
}

`bonus-coin-reset` type

Payload

interface PublicBonusCoinResetPayload {
  /**
   * ISO
   */
  resetAt: string
}

`profile-link-success` type

Payload

interface PublicProfileLinkSuccessPayload {
  profileType: 'tiktok' | 'pulsoid' // ValidLinkedProfileType
}

`profile-link-failure` type

Payload

interface PublicProfileLinkFailurePayload {
  profileType: 'tiktok' | 'pulsoid' // ValidLinkedProfileType
}

`profile-unlink` type

Payload

interface PublicProfileUnlinkPayload {
  profileType: 'tiktok' | 'pulsoid' // ValidLinkedProfileType
}

`user-ban-update` type

Payload

interface PublicUserBanUpdatePayload {
  type: 'ban' | 'unban'
  user: {
    // MinimalUserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile?: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID?: string
  }
}

`command-request` type

Command Requests are sent to the client to trigger a specific action on the client side such as reloading the menu or balance or executing a command

Payload

type Command = 'reload-menu' | 'reload-balance' | 'reload-commands'
interface PublicCommandRequestPayload {
  command: Command | Command[]
}

`prv` domain

Primarily the same as the pub events but with extra information related to costs and revenue, such as price, unitPrice, payments, and split.

`effect-request` type [prv]

Payload

interface PrivateEffectRequestPayload {
  effect: {
    // GameSessionEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    price: number
    pool?: number
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  origin?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  requester?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  sourceDetails?: // SourceDetails
  | {
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        currency: string
        cost: number
        donationID: string
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  price: number
  unitPrice: number
  payments?: {
    global: {
      free: number
      paid: number
    }
    local: {
      free: number
      paid: number
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`timed-effect-update` type [prv]

Payload

interface PrivateTimedEffectUpdatePayload {
  status: 'begin' | 'end' | 'pause' | 'resume' // GameSessionTimedEffectStatus
  /**
   * Time remaining on the effect in milliseconds
   */
  timeRemaining: number
  effect: {
    // GameSessionEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    price: number
    pool?: number
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  origin?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  requester?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  sourceDetails?: // SourceDetails
  | {
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        currency: string
        cost: number
        donationID: string
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  price: number
  unitPrice: number
  payments?: {
    global: {
      free: number
      paid: number
    }
    local: {
      free: number
      paid: number
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-success` type [prv]

Payload

interface PrivateEffectSuccessPayload {
  effect: {
    // GameSessionEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    price: number
    pool?: number
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  origin?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  requester?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  sourceDetails?: // SourceDetails
  | {
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        currency: string
        cost: number
        donationID: string
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  price: number
  unitPrice: number
  payments?: {
    global: {
      free: number
      paid: number
    }
    local: {
      free: number
      paid: number
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-refund` type [prv]

Payload

interface PrivateEffectRefundPayload {
  effect: {
    // GameSessionEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    price: number
    pool?: number
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  origin?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  requester?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  sourceDetails?: // SourceDetails
  | {
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        currency: string
        cost: number
        donationID: string
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  price: number
  unitPrice: number
  payments?: {
    global: {
      free: number
      paid: number
    }
    local: {
      free: number
      paid: number
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-retry` type [prv]

Payload

interface PrivateEffectRetryPayload {
  effect: {
    // GameSessionEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    price: number
    pool?: number
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  origin?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  requester?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  sourceDetails?: // SourceDetails
  | {
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        currency: string
        cost: number
        donationID: string
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  price: number
  unitPrice: number
  payments?: {
    global: {
      free: number
      paid: number
    }
    local: {
      free: number
      paid: number
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`effect-failure` type [prv]

Payload

interface PrivateEffectFailurePayload {
  temporary?: boolean
  message?: string
  effect: {
    // GameSessionEffectPayloadEffectData
    effectID: string // EffectID
    type: 'game' | 'overlay' | 'sfx'
    name:
      | string
      | {
          public: string
          sort?: string
        }
    image: string
    price: number
    pool?: number
    note?: string
    description?: string
    tags?: string[]
    disabled?: boolean
    new?: boolean
    inactive?: boolean
    admin?: boolean
    category?: string[]
    group?: string[]
    tiktok?: {
      name: string
      image: string
      id: number
      duration?: {
        value: number
        immutable?: boolean
      }
    }
    sessionCooldown?: {
      startTime: number
      duration: number
    }
    userCooldown?: {
      startTime: number
      duration: number
    }
    scale?: {
      duration: number
      percent: number
      startTime: number
      startScale: number
    }
    hidden?: boolean
    unavailable?: boolean
  }
  target: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  origin?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  requester?: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  sourceDetails?: // SourceDetails
  | {
        type: 'crowd-control-test'
      }
    | {
        type: 'crowd-control-retry'
      }
    | {
        name: string
        type: 'twitch-channel-reward'
        rewardID: string
        redemptionID: string
        twitchID: string
        cost: number
      }
    | {
        type: 'crowd-control-chaos-mode'
      }
    | {
        type: 'pulsoid-trigger'
        cooldown: number
        heartRate: number
        uuid: string
        triggerType: 'rise-above' | 'fall-below'
        targetHeartRate: number
        holdTime: number
      }
    | {
        name: string
        type: 'tiktok-gift'
        userID: string
        cost: number
        giftName: string
        giftID: number
        transactionID?: string
      }
    | {
        type: 'stream-labs-donation'
        currency: string
        cost: number
        donationID: string
        name?: string
        message?: string
      }
  anonymous?: boolean
  game: {
    // GameRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  gamePack: {
    // GamePackRecord
    gamePackID: string // GamePackID
    platform:
      | 'GB'
      | 'GBA'
      | 'GCN'
      | 'GEN'
      | 'GG'
      | 'IOT'
      | 'N64'
      | 'NES'
      | 'Other'
      | 'PC'
      | 'PS1'
      | 'PS2'
      | 'SNES'
      | 'Wii'
      | 'WiiU' // GamePackPlatform
    name: string
    proExclusive?: boolean
    image?: string
  }
  /**
   * The parameter options chosen by the viewer.
   */
  parameters?: {
    // EffectRequestParameters
    /**
     * The internal developer ID of the parameter.
     */
    [parameterID: string]: {
      /**
       * The display name of the parameter.
       */
      title: string
      /**
       * The type of the parameter.
       * `hex-color` is currently unused.
       */
      type: 'options' | 'hex-color'
      /**
       * The internal developer ID of the chosen value.
       */
      value: string
      /**
       * The display name of the chosen value.
       * Undefined when `type` is not `options`.
       */
      name?: string
    }
  }
  price: number
  unitPrice: number
  payments?: {
    global: {
      free: number
      paid: number
    }
    local: {
      free: number
      paid: number
    }
  }
  pooled?: boolean
  quantity?: number
  requestID: string // GameSessionRequestID
  timestamp: number
  example?: boolean
  localTimestamp?: number
}

`coin-exchange` type

Payload

interface PrivateCoinExchangeEvent {
  amount: number
  coinType: 'free' | 'paid'
  target: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  exchanger: {
    // UserRecord
    ccUID: string // CrowdControlUserID
    image: string
    name: string
    profile: // ProfileType
    'twitch' | 'tiktok' | 'youtube' | 'discord' | 'tiktok-gifter' | 'pulsoid'
    originID: string
    subscriptions: ('pro' | 'tiktok')[]
    roles: (
      | 'admin'
      | 'ambassador'
      | 'trial'
      | 'debug'
      | 'dev'
      | 'partner'
      | 'staff'
    )[]
    split?: number
  }
  source?: // ExchangeSource
  | 'paypal'
    | 'stripe'
    | 'tiltify'
    | 'twitch-bits'
    | 'twitch-channel-points-redemption'
    | 'twitch-sub'
  timestamp: number
  transactionID: string // TransactionID
  example?: boolean
  anonymous?: boolean
  bonus?: number
}

WebSocket Requests

Requests take the form of...

interface Request {
  action: string
  data: unknown
}

...where data is defined in the following sections for each event.

`whoami` action

Asks the server for your Connection ID, which is necessary for allowing a user to sign in to your application. The request accepts no data.

See whoami event for the server's response.

`subscribe` action

Ask the server to send events from the specified topics.

See subscription-result event for the server's response.

Data

interface SubscribeData {
  /**
   * A complete JWT auth token
   */
  token?: string
  /**
   * A partial token obtained from the Overlay URL with limited backend access
   */
  key?: string
  /**
   * PubSub topics are in the format of:
   * <domain>/<scope>/<target> or
   * <domain>/<target>
   * All domains are available here except direct as it is reserved for direct messages
   * from the server to a specific connection
   */
  topics: string[] // PubSubEventTopicSchema
}

`checksum` action

Data

interface ChecksumData {
  token: string
}

`rpc` action

Invokes an action on a user, typically their game session. See below subheadings for available calls.

Data

interface RPCData {
  token: string
  call: unknown
}

`effectResponse` call

Call

interface BaseEffectResponse {
  /**
   * `requestID` of the invoking `effect-request`
   */
  request: string
  /**
   * Current UTC time in unix seconds
   */
  stamp: number
  /**
   * Message to display to the viewer
   */
  message: string
}

interface InstantEffectResponse extends BaseEffectResponse {
  status: 'success' | 'failTemporary' | 'failPermanent' | 'timedEnd'
}

interface TimedEffectResponse extends BaseEffectResponse {
  status: 'timedBegin' | 'timedPause' | 'timedResume' | 'delayEstimated'
  timeRemaining: number
}

type EffectResponse = InstantEffectResponse | TimedEffectResponse

interface EffectResponseCall {
  id: string
  type: 'call'
  method: 'effectResponse'
  args: [EffectResponse]
}

`effectReport` call

Call

interface EffectReportCall {
  id: string
  type: 'call'
  method: 'effectReport'
  args: {
    id: string
    ids: string[]
    effectType?: 'overlay' | 'game' | 'sfx'
    identifierType?: 'effect' | 'group' | 'category'
    stamp: number
    status: 'menuAvailable' | 'menuUnavailable' | 'menuVisible' | 'menuHidden'
  }[]
}

WebSocket API Reference ​

WebSocket Events ​

direct domain ​

subscription-result type ​

whoami type ​

login-success type ​

login-failure type ​

bad-request type ​

game-session-checksum-update type [direct] ​

pub domain ​

game-session-start type ​

game-session-stop type ​

lobby-user-update type ​

lobby-user-remove type ​

effect-request type [pub] ​

timed-effect-update type [pub] ​

effect-success type [pub] ​

effect-refund type [pub] ​

effect-retry type [pub] ​

effect-failure type [pub] ​

game-session-menu-update type ​

game-session-menu-sync type ​

pro-subscription-update type ​

bonus-coin-reset type ​

profile-link-success type ​

profile-link-failure type ​

profile-unlink type ​

user-ban-update type ​

command-request type ​

prv domain ​

effect-request type [prv] ​

timed-effect-update type [prv] ​

effect-success type [prv] ​

effect-refund type [prv] ​

effect-retry type [prv] ​

effect-failure type [prv] ​

coin-exchange type ​

WebSocket Requests ​

whoami action ​

subscribe action ​

checksum action ​

rpc action ​

effectResponse call ​

effectReport call ​

WebSocket API Reference

WebSocket Events

`direct` domain

`subscription-result` type

`whoami` type

`login-success` type

`login-failure` type

`bad-request` type

`game-session-checksum-update` type [direct]

`pub` domain

`game-session-start` type

`game-session-stop` type

`lobby-user-update` type

`lobby-user-remove` type

`effect-request` type [pub]

`timed-effect-update` type [pub]

`effect-success` type [pub]

`effect-refund` type [pub]

`effect-retry` type [pub]

`effect-failure` type [pub]

`game-session-menu-update` type

`game-session-menu-sync` type

`pro-subscription-update` type

`bonus-coin-reset` type

`profile-link-success` type

`profile-link-failure` type

`profile-unlink` type

`user-ban-update` type

`command-request` type

`prv` domain

`effect-request` type [prv]

`timed-effect-update` type [prv]

`effect-success` type [prv]

`effect-refund` type [prv]

`effect-retry` type [prv]

`effect-failure` type [prv]

`coin-exchange` type

WebSocket Requests

`whoami` action

`subscribe` action

`checksum` action

`rpc` action

`effectResponse` call

`effectReport` call