Dashboard

BetterTTV WebSocket

We use WebSockets to send and receive updates to and from clients.

wss://sockets.betterttv.net/ws

Join Channel

SENDjoin_channel

Joining a channel will subscribe you to its events, such as emote and user updates.

Message Data Structure

FieldTypeDescription
nameChannelNameThe name of the channel to join.

Example Message

{
  "name": "join_channel",
  "data": {
    "name": "{provider}:{providerId}"
  }
}

Part Channel

SENDpart_channel

Parting a channel will unsubscribe you from its events.

Message Data Structure

FieldTypeDescription
nameChannelNameThe name of the channel to join.

Example Message

{
  "name": "part_channel",
  "data": {
    "name": "{provider}:{providerId}"
  }
}

Emote Create

RECEIVEemote_create

Create events are sent when a new emote is uploaded to the subscribed channel, or when a new shared emote is added.

Event Data Structure

FieldTypeDescription
emoteEmoteThe emote that was created.
channelChannelNameThe channel that the emote was created in.

Example Event

{
  "name": "emote_create",
  "data": {
    "emote": {
      "id": "5f1b0186cf6d2144653d2970",
      "code": "catJAM",
      "imageType": "gif",
      "animated": true,
      "user": {
        "id": "5f17a10cfe85fb4472d107b4",
        "name": "madlittlecat",
        "displayName": "MadLittleCat",
        "providerId": "36646922"
      }
    },
    "channel": "twitch:38974721"
  }
}

Emote Update

RECEIVEemote_update

This event will be triggered when an emote's code is modified. In addition, this event will be emitted when a shared emote's code-alias is updated.

Event Data Structure

FieldTypeDescription
emote.idstringThe ID of the emote that was updated.
emote.codestringThe new code of the emote.
channelChannelNameThe channel that the emote was created in.

Example Event

{
  "name": "emote_update",
  "data": {
    "emote": {
      "id": "5f1b0186cf6d2144653d2970",
      "code": "dogJAM"
    },
    "channel": "twitch:38974721"
  }
}

Emote Delete

RECEIVEemote_delete

This event will be triggered when an emote is deleted from a subscribed channel.

Event Data Structure

FieldTypeDescription
emoteIdstringThe ID of the emote that was deleted.
channelChannelNameThe channel that the emote was deleted from.

Example Event

{
  "name": "emote_delete",
  "data": {
    "emoteId": "5f1b0186cf6d2144653d2970",
    "channel": "twitch:38974721"
  }
}

User Broadcast

SENDbroadcast_me

Broadcasts your user information, if any, to other clients in the same channel. This should be sent when messages are sent by the user.

Message Data Structure

FieldTypeDescription
providerProviderThe name of the platform.
providerIdstringPlatform user Id for specified provider.
channelChannelNameThe channel that the emote was created in.

Example Message

{
  "name": "broadcast_me",
  "data": {
    "provider": "twitch",
    "providerId": "38974721",
    "channel": "twitch:91067577"
  }
}

User Update

RECEIVElookup_user

Usually on channel join, this is event is triggered when a user broadcasts themselves to other clients.

Event Data Structure

FieldTypeDescription
namestringUser's platform username.
providerIdstringUser's platform user id.
channelChannelNameThe channel the change occured in.
probooleanWhether the user is a pro subscriber.
emotesEmote[]List of the user's personal emotes.
badge?.urlstringThe URL of the user badge.
badge?.startedAt?stringDate when user first subscribed to Pro.

Example Event

{
  "name": "lookup_user",
  "data": {
    "name": "vasp",
    "providerId": "38974721",
    "channel": "twitch:91067577",
    "pro": true,
    "emotes": [
      {
        "id": "61f013ba06fd6a9f5be219f3",
        "code": "COPIUM",
        "imageType": "png",
        "animated": false,
        "user": {
          "id": "5ebda868f0fb3f168c4b64e1",
          "name": "dzurekk",
          "displayName": "Dzurekk",
          "providerId": "447870355"
        }
      }
    ],
    "badge": {
      "url": "https://cdn.betterttv.net/badges/pro/0b58eba8-e49c-4ed7-ae7d-be0b524502e6.png",
      "startedAt": "2020-12-01T00:00:00.000Z"
    }
  }
}

Channel Name Structure

Channel name is a concatted string, with provider and providerId.

{provider}:{providerId}
FieldTypeDescription
providerProviderThe name of the platform.
providerIdstringPlatform user Id for specified provider.