Social Stream API

Reading the Social Stream

The Social Stream messages can be fetched with simple HTTP GET requests. They do not require OAuth2 authentication, so the "Authorization" header should not be sent on these queries.

The first social stream request

The first social stream request should be the following HTTP GET request:

http://socialstream.ustream.tv/socialstream/get.json/CHANNEL_ID/default

The CHANNEL_ID value is the same as the "id" field in the channel list response.

The result will be a JSON string:

{
  "success":true,
  "refreshInterval":10,
  "range":[0,1302176480],
  "payload":[
	{
	  "uid":1
	  "type":"msg",
	  "text":"MESSAGE_TEXT",
	  "createdAt":"UTC_TIMESTAMP",
	  "isOwner":0,
	  "profilePictureUrl":"http://static.ustream.tv/na.jpg",
	  "profileNetwork":"twitter",
	  "profileUserName":"Gyula",
	  "network":[
		{
		  "provider":"twitter",
		  "displayName":"Gyula"
		}
	  ]
	}
  ]
}

The social stream messages are dictionaries under the "payload" array.

The message fields
name description
uid unique identifier of the message
type "msg" for social stream messages. See section 5.1.3. for other types of messages
createdAt UTC timestamp of the message
isOwner 1 if the message was sent by the owner of the channel, 0 otherwise.
profilePictureUrl profile picture of the sender
profileNetwork the social network that is shown for the message on the website. Supported values: "twitter", "facebook", "ustream".
profileUserName sender username on the profileNetwork
network array of social networks the user belongs to. Under network "provider" contains the social network type (supported values: "twitter", "facebook", "ustream"), "displayName" contains the sender name on the social network.

Querying new social stream messages

The initial social stream request (see previous chapter) should be called only at the beginning of the session. After the first request the new social stream messages should be queried in timeslices:

http://socialstream.ustream.tv/socialstream/get.json
/CHANNEL_ID/timeslice/RANGE/REFRESH_INTERVAL

The parameter "RANGE" refers to the second value of the "range" array in the previous request. "REFRESH_INTERVAL" refers to the "refreshInterval" value in the previous request.

The response of this query has the same format as described in Chapter 5.1.1. The client should take extra care of the following:

  • Refresh interval can change during the session. Clients should adjust timers to the intervals defined by the response.
  • In order to prevent time shift, clients should store the first range value as the start timestamp, and adjust the time of the requests properly.
  • Example: if the first timestamp is 1000 (queried at START_TS) and the client is currently requesting /timeslice/1100/10) which contains a refreshInterval=5, it should query the next timeslice (/timeslice/1110/5) at ts=START_TS+110

Special social stream messages

The "payload" section can contain the following extra messages:

Changing the social stream host

When this message is received the next query should be done on the new server with a /default request:

{
	"type": "host",
	"host": "http://socialstream2.ustream.tv"
}

Ignoring a message

When this message is received the client should remove the given message from the chat window:

{
	"type": "ignMsg",
	"uid": "123456"
}

Ignoring a user

When this message is received the client should remove all messages from the chat window for the given user, and ignore all the later messages as well:

{
	"type": "ignUser",
	"network": [{"provider":"twitter", "displayName":"Gyula"}]
}

Unignoring a user

When this message is received the client should allow the further messages of the given user to appear in the chat window:

{
	"type": "unIgnUser",
	"network": [{"provider":"twitter", "displayName":"Gyula"}]
}

Writing to the Social Stream

Sending messages to the Social Stream is currently not available for third parties.