WebSocket

EventSub notifications can also be received over websockets, aka EventSockets.

When using websockets, you create eventsub subscriptions with a user access token.

For each user ID, you can create up to 900 enabled subscriptions (but max_total_cost is only 10 across all subscriptions for that client_id-user_id tuple).

Twitch4J automatically creates additional websockets to comply with Twitch's limits (each websocket can have up to 300 enabled subscriptions, and each user ID can create up to 3 websocket connections for a given client ID).

warning

Due to Twitch restrictions, we create separate websockets for each user ID. If you are creating EventSocket subscriptions with tokens from many different users, it may be apt to switch to webhooks or conduits to avoid spawning too many websockets.

Module Creation

You can create an IEventSubSocket instance via TwitchClientBuilder or directly via TwitchEventSocketPool.

If and only if you pass the user access token in the module builder, you can utilize IEventSubSocket#register without specifying the token again.

Shared

Java

ITwitchClient twitchClient = TwitchClientBuilder.builder()
    .withEnableEventSocket(true)
    .withEnableHelix(true)
    .withDefaultAuthToken(new OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build();
IEventSubSocket eventSocket = twitchClient.getEventSocket();

Kotlin

val twitchClient = TwitchClientBuilder.builder()
    .withEnableEventSocket(true)
    .withEnableHelix(true)
    .withDefaultAuthToken(OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build()
val eventSocket = twitchClient.getEventSocket()

Groovy

def twitchClient = TwitchClientBuilder.builder()
    .withEnableEventSocket(true)
    .withEnableHelix(true)
    .withDefaultAuthToken(new OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build()
def eventSocket = twitchClient.getEventSocket()

Standalone

Java

IEventSubSocket eventSocket = TwitchEventSocketPool.builder()
    .fallbackToken(new OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build();

Kotlin

val eventSocket = TwitchEventSocketPool.builder()
    .fallbackToken(OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build()

Groovy

def eventSocket = TwitchEventSocketPool.builder()
    .fallbackToken(new OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build()

info

While TwitchEventSocketPool can safely be used directly, be wary of directly using TwitchSingleUserEventSocketPool.builder() or TwitchEventSocket.builder(). The former does not support tokens from different user IDs and the latter does not support more than 300 enabled subscriptions.

Subscription Management

To create EventSocket subscriptions, it is easiest to use the IEventSubSocket#register(EventSubSubscription) method.

If you did not specify a default user token in the module builder, you must utilize IEventSubSocket#register(OAuth2Credential, EventSubSubscription) (the first argument should be a user access token).

It is easiest to create EventSubSubscription instances through our SubscriptionTypes utility class.

Java

eventSocket.register(
    SubscriptionTypes.STREAM_ONLINE.prepareSubscription(
        builder -> builder.broadcasterUserId("channel-id-goes-here").build(),
        null
    )
);

Kotlin

eventSocket.register(
    SubscriptionTypes.STREAM_ONLINE.prepareSubscription(
        { builder -> builder.broadcasterUserId("channel-id-goes-here").build() },
        null
    )
)

Groovy

eventSocket.register(
    SubscriptionTypes.STREAM_ONLINE.prepareSubscription(
        { builder -> builder.broadcasterUserId("channel-id-goes-here").build() },
        null
    )
)

warning

The following EventSub subscription types are only supported by webhooks: drop.entitlement.grant, extension.bits_transaction.create, user.authorization.grant, and user.authorization.revoke.

Events

In addition to firing the corresponding events for each subscription type, the websocket module can also fire the following meta-events:

• EventSocketSubscriptionSuccessEvent: Called when an EventSocket successfully registers a subscription with the Helix API.
• EventSocketSubscriptionFailureEvent: Called when an EventSocket fails to register subscription with the Helix API.
• EventSocketDeleteSubscriptionSuccessEvent: Called when an EventSocket successfully deletes a subscription via the Helix API.
• EventSocketDeleteSubscriptionFailureEvent: Called when an EventSocket fails to delete a subscription via the Helix API.
• EventSocketConnectionStateEvent: Called when the connection state of an EventSocket changes.
• EventSocketClosedByTwitchEvent: Called when Twitch decides to close our EventSocket.

Code Example

Java

// build module
ITwitchClient twitchClient = TwitchClientBuilder.builder()
    .withEnableEventSocket(true)
    .withEnableHelix(true)
    .withDefaultAuthToken(new OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build();
IEventSubSocket eventSocket = twitchClient.getEventSocket();

// create subscription
eventSocket.register(
    SubscriptionTypes.STREAM_ONLINE.prepareSubscription(
        b -> b.broadcasterUserId("channel-id-goes-here").build(),
        null
    )
);

// register event handler
eventSocket.getEventManager().onEvent(StreamOnlineEvent.class, System.out::println);

Kotlin

// build module
val twitchClient = TwitchClientBuilder.builder()
    .withEnableEventSocket(true)
    .withEnableHelix(true)
    .withDefaultAuthToken(OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build()
val eventSocket = twitchClient.getEventSocket()

// create subscription
eventSocket.register(
    SubscriptionTypes.STREAM_ONLINE.prepareSubscription(
        { b -> b.broadcasterUserId("channel-id-goes-here").build() },
        null
    )
)

// register event handler
eventSocket.getEventManager().onEvent(StreamOnlineEvent::class.java) {
    println(it)
}

Groovy

// build module
def twitchClient = TwitchClientBuilder.builder()
    .withEnableEventSocket(true)
    .withEnableHelix(true)
    .withDefaultAuthToken(new OAuth2Credential("twitch", "user-access-token-goes-here"))
    .build()
def eventSocket = twitchClient.getEventSocket()

// create subscription
eventSocket.register(
    SubscriptionTypes.STREAM_ONLINE.prepareSubscription(
        { b -> b.broadcasterUserId("channel-id-goes-here").build() },
        null
    )
)

// register event handler
eventSocket.getEventManager().onEvent(StreamOnlineEvent) { event ->
    System.out.println event
}