Twitch.tv pubsub client

Author

• Lauri Orgla theorx@hotmail.com

Description

PUBSUB Websocket api client implementation written in golang, motivation was to build a client that actually works. There are other implementations that are not working so well or are not working at all. This implementation covers all publicly documented behaviours of the pubsub api and also one undocumented moderation actions topic.

• Documentation to official twitch api Twitch pubsub doc

Connection handling

Twitch requires to send a PING message at least once per 5 minutes. This implementation is sending a PING every 60 seconds.

Twitch states that every ping request should receive a response within 10 seconds, this implementation will wait up to 20 seconds before going to a reconnect state

In case of RECONNECT or failing to receive a PONG all the current topics that you have subscribed to will get resubscribed automatically

For example:

//you create a client c
c.Subscribe(..)
//now RECONNECT happens
//you will not need to call Subscribe again, the topics will be subscribed to
//on the new connection automatically

API Overview

• Set*Handler functions are for setting handler functions to the types of topics you have subscribed to

	client.SetCatchAllHandler(func(message TTVClient.IncomingMessage) {})
	client.SetLogFunction(func(i ...interface{}) {})
	client.SetBitsHandler(func(message TTVClient.BitsMsg) {})
	client.SetModerationHandler(func(message TTVClient.ModerationActionMsg) {})
	client.SetCommerceHandler(func(message TTVClient.CommerceMsg) {})
	client.SetBitsBadgeHandler(func(message TTVClient.BitsBadgeMsg) {})
	client.SetSubscriptionsHandler(func(message TTVClient.SubscriptionMsg) {})
	client.SetWhisperHandler(func(message TTVClient.WhisperMsg) {})
	client.SetUnknownHandler(func(message TTVClient.IncomingMessage) {})

• CreateClient creates the client, expects access token and twitch websocket endpoint
• There is one predefined constant: TTVClient.TwitchPubSubHost which corresponds to: wss://pubsub-edge.twitch.tv/
• Endpoint required for CreateClient requires correct prefix wss://

	TTVClient.CreateClient("your-access_token", TTVClient.TwitchPubSubHost)

• Subscribe/unsubscribe have the same signature
• Both of the operations require a slice of Topics - []Topic.Topic

	client.Subscribe([]Topic.Topic{
		Topic.Bits(1),
		Topic.BitsBadgeNotification(1),
		Topic.Commerce(1),
		Topic.Whispers(1),
		Topic.Subscriptions(1),
		Topic.ModerationAction(1, 2),
	})

	client.Unsubscribe([]Topic.Topic{
		Topic.Bits(1),
		Topic.BitsBadgeNotification(1),
		Topic.Commerce(1),
		Topic.Whispers(1),
		Topic.Subscriptions(1),
		Topic.ModerationAction(1, 2),
	})

• Topic.Bits(channel id)

• Topic.BitsBadgeNotification(channel id)

• Topic.Commerce(channel id)

• Topic.Whispers(user id)

• Topic.Subscriptions(channel id)

• Topic.ModerationAction(user id, channel id)

• Closing the connection - client.Close()

Errors

• TTVClient.ErrorOperationFailed = errors.New("sub/unsub operation failed") <- In this case usually the credentials are incorrect
• TTVClient.ErrorNotConnected = errors.New("not connected") <- Connection is down / TTVClient has been closed

Usage example

package main

import (
	"github.com/theorx/go-ttv-pubsub/pkg/TTVClient"
	"github.com/theorx/go-ttv-pubsub/pkg/Topic"
	"log"
	"time"
)

func main() {

	//create a connection
	client, err := TTVClient.CreateClient("your-access_token", TTVClient.TwitchPubSubHost)

	if err != nil {
		log.Fatal("Failed to connect", err)
		return
	}

	//set up handlers before subscribing

	client.SetModerationHandler(func(message TTVClient.ModerationActionMsg) {
		log.Println("Moderation event received", message)
	})

	err = client.Subscribe(
		[]Topic.Topic{
			Topic.ModerationAction(64417816, 64417816),
		},
	)

	if err != nil {
		log.Println(err)
		return
	}

	time.Sleep(time.Second * 60)

	log.Println(client.Close())
}