Skip to content
This repository has been archived by the owner on Jan 19, 2021. It is now read-only.

WebSocket API

Jump to bottom
John Regan edited this page Jul 21, 2017 · 1 revision

The websocket API is used to get live updates and for reading/writing chat messages.

You'll need an access token (see the JSON API docs for information on getting one), then connect to:

ws://example.com/ws/:id?token=(token)

Once connected, you can send and receive JSON messages.

All JSON objects sent over WebSocket have a "type" key.

Status message

The status message arrives when something about the stream has updated.

The status message will contain information on the listed accounts, including whether or not that account is live (the live key), whether chat messages/comments are writable (the writable key), network information, and whether or not that account is actually ready for sending chat messages and comments (the ready key).

You can request a status update at anytime by sending an empty status message, ie:

{
    "type":"status"
}

Example Messages

Stream goes live

{
   "type" : "status",
   "status" : {
      "data_pulling" : false,
      "data_pushing" : true,
      "data_incoming" : true
   },
   "accounts" : {
      "14" : {
         "live" : true,
         "writable" : true,
         "name" : "jprjrdev",
         "network" : {
            "displayName" : "Twitch",
            "name" : "twitch"
         },
         "ready" : true,
         "http_url" : "https://twitch.tv/jprjrdev"
      },
      "17" : {
         "network" : {
            "displayName" : "Twitch",
            "name" : "twitch"
         },
         "writable" : true,
         "name" : "gamethattunedev",
         "ready" : false,
         "live" : false
      },
      "0" : {
         "name" : "john",
         "ready" : true,
         "network" : {
            "displayName" : "IRC",
            "name" : "irc"
         },
         "live" : false,
         "writable" : true
      }
   }
}

Stream ends

{
   "type" : "status",
   "status" : {
      "data_incoming" : false,
      "data_pulling" : false,
      "data_pushing" : false
   },
   "accounts" : {
      "0" : {
         "writable" : true,
         "name" : "john",
         "live" : false,
         "ready" : true,
         "network" : {
            "name" : "irc",
            "displayName" : "IRC"
         }
      }
   }
}

Writer / Writerresult Message

If an account is available for writing (writable = true) but not ready to actually send messages (ready = false), you'll need to sent a writer message to request a chat writer be created.

When you (or anybody else on the stream) creates a chat writer, they'll receive a writerresult message.

Writer message:

  • type - "writer"
  • account_id - the account you want to send messages from
  • cur_stream_account_id - the account you want to send messages to
{
   "type" : "writer",
   "account_id" : 17,
   "cur_stream_account_id" : 14
}

Writerresult message

The writerresult message is only sent once a writer has been successfully created.

{
   "type" : "writerresult",
   "account_id" : 17,
   "cur_stream_account_id" : 14
}

viewcount / viewcountresult message

The viewcount message is used to request the current viewer count.

The viewcountresult message will contain the current number of viewers for a stream.

Viewcount message

{
    "type" : "viewcount"
}

Viewcountresult message

{
   "type" : "viewcountresult",
   "viewer_count" : 0,
   "stream_id" : 21,
   "account_id" : 14
}

Text Message / Emote Message

The text and emote message types are for sending/receiving chat messages and emotes.

Sending text/emotes

To send a message, specify:

  • type - either text or emote
  • account_id - the account id to send from
  • cur_stream_account_id - the stream account to send to
  • text - the text of your message or emote

Example: sending an internal IRC message

{
   "type" : "text",
   "account_id" : 0,
   "cur_stream_account_id" : 0,
   "text" : "sending an IRC message"
}

Example: sending an internal IRC private message (begin message with /msg user)

{
   "text" : "/msg somebody hey this is a private message",
   "account_id" : 0,
   "cur_stream_account_id" : 0,
   "type" : "text"
}

Example: sending a twitch message - same account that's streaming

{
   "type" : "text",
   "account_id" : 14,
   "cur_stream_account_id" : 14,
   "text" : "Sending a message!!!"
}

Example: sending a twitch message - from account is different than streaming account

{
   "type" : "text",
   "account_id" : 17,
   "cur_stream_account_id" : 14,
   "text" : "Here's one where I'm not the streaming account"
}

Example: receiving an internal IRC message

{
   "type" : "text",
   "account_id" : 0,
   "network" : "irc",
   "from" : {
      "id" : 2,
      "name" : "test"
   },
   "text" : "yay",
   "markdown" : "yay"
}

Example: receiving an internal IRC private message (notice the presence of a to key)

{
   "type" : "text",
   "account_id" : 0,
   "network" : "irc",
   "from" : {
      "id" : 2,
      "name" : "test"
   },
   "to" : {
      "name" : "john",
      "id" : 1
   },
   "text" : "hey ban this guy",
   "markdown" : "hey ban this guy"
}

Example: receiving a twitch message

{
   "type" : "text",
   "stream_id" : 21,
   "account_id" : 14,
   "network" : "twitch",
   "text" : "here's a message from twitch Kappa",
   "markdown" : "here's a message from twitch ![Kappa](http://static-cdn.jtvnw.net/emoticons/v1/25/1.0)",
   "from" : {
      "id" : "146521877",
      "name" : "gamethattunedev"
   }
}

Example: receiving a twitch emote

{
   "type" : "emote",
   "stream_id" : 21,
   "account_id" : 14,
   "network" : "twitch",
   "text" : "is loving this",
   "markdown" : "is loving this",
   "from" : {
      "name" : "gamethattunedev",
      "id" : "146521877"
   }
}
Clone this wiki locally