hsp.init(params)

Initializes the JS API and loads the theme CSS files.

params: object:

• apiKey (string)
• receiverPath (string, optional) Absolute URL of your app_receiver.html file. This must start with http(s)://
• useTheme (int, optional) Set to 1 to use current dashboard theme.
• subtitle (string, optional) The subtitle of your app, to be displayed in the stream's title.
• callBack (function, optional) Init will send an error message to the callBack function after initialization. The message is: No Error, if initialization is successful.

hsp.init({
	apiKey: 'abcd123',
	receiverPath: 'http://app.domain.com/my_receiver.html',
	useTheme: true,
	callBack: function( message ){ console.log('Error: ' + message); }
});

hsp.bind(eventName, callback)

Registers an event handler for a specified event.

Note: This requires the App Receiver to be set up.

eventName: (string)

Name of the event to handle, can be one of the following:

• closepopup - Fires when a custom popup opened by your app stream is closed
• dropuser - Fires when a user drags & drops a Twitter user avatar from the HootSuite dashboard into your app stream
• refresh - Fires when the app column is refreshed, either by the user within the stream, or as part of a dashboard refresh
• sendtoapp - Registering for this event will cause users to see a menu item reading Send to <app stream>...in Twitter and Facebook stream message menus. This event is fired when users click on the menu item

callback: (function)

Function to handle the callback, the function's parameters are determined by the event. See the events section for details on expected callback formats.

hsp.bind('refresh', function() {
	window.location.reload();
});

As stated in the Best Practices section, it makes sense to suppress reloading of the stream while the user interacts with it (e.g. posting messages, expanded details, possibly scroll position not near the top). A possible approach could look something like this:

hsp.bind('refresh', function() {
	// collect any text the user has entered into a comment entry box
	$(".hs_commentEntry textarea").each(function() {
		comments += $(this).val();	
	});
	if(			
		comments == '' // comment entry boxes are empty
			&& $(window).scrollTop() < 15 // user has not scrolled down more than 15px		
	) {
	window.location.reload();						
}
});

The use of window.location.reload() is obviously not the best approach and was used mostly for simplicity of the examples. One of the most elegant solutions would be to poll for any new messages via AJAX and to inject only new messages into the DOM while leaving existing messages untouched.

hsp.clearStatusMessage()

Removes all currently visible status messages.

hsp.composeMessage(message, params)

Opens the Share to Social Networks dialog in the HootSuite dashboard.

message: (string)

Twitter message rules apply, eg. to compose a DM to @HootSuite would be: d hootsuite <your message here>

params: (object, optional):

• shortenLinks: bool, optional Shorten all links found in message with user's default URL shortener (ow.ly / ht.ly / or vanity url). Defaults to false.
• timestamp: bool OR int, optional Open the Scheduler and populate it with the timestamp (in GMT). If true is passed in, then the Scheduler will open with no default time. Defaults to false.

hsp.composeMessage( 'message text', { shortenLinks: true } );

hsp.customUserInfo(data)

Opens a user info popup window.

data (JSON object)

var data = {
	"fullName": "David Chan",
	"screenName": "@chandavid",
	"avatar": "http://a3.twimg.com/profile_images/1121921263/dc.png",
	"profileUrl": "http://twitter.com/chandavid",
	"userLocation": "Vancouver, BC",
	"bio": "JavaScript/web/martini developer. Working on @HootSuite. Making by breaking.",
	"extra": [
		{"label": "Age", "value": "Unknown"},
		{"label": "Gender", "value": "Male"}
	],
	"links": [
		{"label": "HootSuite", "url": "http://hootsuite.com"},
		{"label": "Blog", "url": "http://blog.hootsuite.com"}
	]
};

hsp.showCustomPopup(src, title, width, height)

Shows a modal popup window containing an iFrame showing content from the specified URL. On close the dialog fires the closePopUp() event.

src (string)

URL of the content to show in the popup

title (string)

The title displayed on the popup window

width (int)

The width in pixels of the popup. The width has the following constraints:

• If not specified, the width defaults to 640 pixels
• The minimum width is 300 pixels.
• The maximum width is 750 pixels.

height (int)

The height in pixels of the popup. The width has the following constraints:

• If not specified, the height defaults to 445 pixels
• The minimum height is 225 pixels.
• The maximum height is 445 pixels.

hsp.showStatusMessage('Done!', 'success') ;					

Please do not initialize hsp again inside the custom popup. Your popup is not supposed to use any hsp functions other than closeCustomPopup(apiKey, pid).

If your popup and app stream/plugin are in the same domain, it is recommended that your popup uses the following javascript function to communicate back to your stream/plugin and run the hsp function: window.parent.frames[apiKey_pid].hsp.some_function().

Note: hsp event binding functions are not available in the custom popup.

hsp.closeCustomPopup(apiKey, pid)

Closes the modal popup window. Note: Please make sure the iFrame page in the custom popup window and the app stream page are sharing the same domain. You don't need to (and shouldn't) call hsp.init() again in the iFrame page, just include hsp.js and call hsp.closeCustomPopup(apiKey, pid). You can use JavaScript to communicate between the popup and the stream like this:

window.parent.frames["<%= apiKey %>_<%= pid %>"].location.reload();				

apiKey (string)

Your app's API Key

pid (string)

The pid is associated with each unique installation of an app stream (or plugin). You can get the pid of each app stream from the url request your server gets. For example:

http://demo.ca/stream.html?lang=en&theme=blue_steel&timezone=-25200&pid=60956&uid=136

hsp.showImagePreview(src, externalUrl)

Shows an image in a popup window, optionally linking to an external URL.

src (string)

Image URL

externalURL (string)

URL to open if user clicks on the image

hsp.showStatusMessage(message, type)

Shows a notification in the top center of the HootSuite dashboard.

message (string)

Should be brief, max. 70 characters.

type (string):

Can be one of the following:

• info: Blue background
• error: Red background
• warning: Yellow background
• success: Green background

hsp.updatePlacementSubtitle(name)

Updates the subtitle of the App's stream.

Note: This requires the App Receiver to be set up (see above).

name (str)

Max 35 characters

hsp.showUser(twitterHandle)

Opens a user info popup for the specified Twitter username.

twitterHandle (string)

Twitter username

hsp.showUser('hootsuite_help');

hsp.showFollowDialog(twitterHandle, isFollow)

Opens a dialog window for following or un-following a Twitter user.

twitterHandle (string)

Twitter username

isFollow (bool)

true to follow, false to unfollow.

hsp.showFollowDialog('hootsuite_help', true);

hsp.getTwitterAccounts(callback)

Gets a list (array) of all Twitter profiles (user names) the logged-in user has added to their HootSuite account.

callback (function)

Function that accepts an array strings

hsp.getTwitterAccounts(console.log); 
// this would log: ["twitteruser_123", "twitter_user_abcd"]

hsp.assignItem(data)

Assign a message, or any text content, to a HootSuite user (self, or team member)

data (JSON object)

var data = {
	"messageId": "1000020",	 //REQUIRED
	"message": "Hi, I'm having an issue with my account",  //REQUIRED
	"userId": 172299,  //optional, but recommended
	"userName": "@chandavid",  //optional, but recommended
	"userAvatar": "https://si0.twimg.com/profile_images/1802089074/dc.jpg",  //optional, but recommended
	"timestamp": 1345051990  //optional, but recommended
};

refresh()

Fires when the app column is refreshed, either by the user within the stream, or as part of a dashboard refresh.

callback format- a function with no parameters

function refreshHandler() { }

dropuser()

Fires when a user drags & drops a Twitter user avatar from the HootSuite dashboard into your app stream

callback format- a function with two parameters, the Twitter handle of the user and the unique ID of the Tweet from which the user was dragged

function dropUserHandler( username, tweetId )
{
	// ...
}

sendcomposedmsgtoapp()

Adds app plugin to the native HootSuite social network selector. User can send messages to the plugin directly from HootSuite compose message box

NOTE: You need to contact our app directory administration team to enable this event binding for your app plugin

callback format- a javascript object containing the message data

Message: (object)
	text: (string)

function sendComposedMsgToAppHandler( message )
{
	// ...
}

function closePopupHandler()
{
	// ...
}

Message: (object)
	version: (string) current version is 1
	post: (object)
		href: (string) url to the original post
		id: (string) external post id
		datetime: (string) iso 8601 datetime format
		source: (string) twitter only e.g. iPhone App
		network: (string)

		user: (object) 
			userid: (string) facebook only
			username: (string)

		attachments: (array)
			items: (array)
				target: (string) url to the resource page
				originurl: (string) url to the actual resource
				thumbnailsrc: (string) url to the thumbnail
			title: (string) 
			type: (string) link | video | photoalbum | photo

		content: (object) 
			body: (string)
			bodyhtml: (string) 
			type: (string)

		conversations: (array)
			id: (int/string)
			uid: (int)
			name: (string)
			text: (string)
			datetime: (string)
			geo: (string) twitter only
			retweetcount: (string) twitter only
			source: (string) twitter only
			profileurl: (string) facebook only
			likes: (int) facebook only

( { 
version:"1",    
    post : { 
		href :  "http://www.facebook.com/photo.php?fbid=1000000", 
		id : "100000000000_9999999999",
		datetime : "2012-04-06T08:27:00", 
		source : " ", 
		network : "facebook", 
		user : {
			userid : "100000000000000", 
			username : "HootSuite"
		}, 
		content : {
			type : "text/html", 
			body : "Preview: the amazing photos ...",
			bodyhtml : "Preview: the amazing photos ..."
		},
		attachments : [
			type : "photo", 
			title: "HootSuite App",
			items : [
				{ 
					target : "http://www.facebook.com/photo.php?fbid=100000",
					originurl : "http://photos-g.ak.fbcdn.net/100000_n.jpg", 
					thumbnailurl : "http://photos-g.ak.fbcdn.net/100000_s.jpg"
				},
				{ 
					target : "http://www.facebook.com/photo.php?fbid=200000",
					originurl : "http://photos-g.ak.fbcdn.net/200000_n.jpg", 
					thumbnailurl : "http://photos-g.ak.fbcdn.net/200000_s.jpg"
				}
			]
		],
		conversation : {
				{
					datetime : "2012-05-15T13:43:32",
					id : "13148577321_394882755588473_38475883",
					likes : 1,
					name : "John Smith",
					profileurl : "http://www.facebook/john.smith",
					text : "That's a very good picture!",
					uid : 2377483482
				}
		}
	} 
} )

function sendToAppHandler( message )
{
	// ...
}

sendprofiletoapp()

Registering for this event will cause users to see a menu item in Twitter, Facebook, LinkedIn and Google+ Page profile menus. The event is fired when users click on the menu item.

callback format- a javascript object containing the profile data

(click on the link to expand)

Profile: (object)
	created_at (string)
	description (string)
	followers_count (int)
	friends_count (int)
	id (int)
	id_str (string)
	lang (string)
	listed_count (int)
	location (string)
	name (string)
	network (string)
	profile_image_url (string)
	profile_image_url_https (string)
	screen_name (string)
	statuses_count (int)
	time_zone (string)
	url (string)
	utc_offset (int)
	verified (boolean)

Profile: (object)
	bio (string)
	first_name (string)
	gender (string)
	id (string)
	last_name (string)
	link (string)
	locale (string)
	name (string)
	network (string)
	picture (string)
	username (string)

Profile: (object)
	first_name (string)
	headline (string)
	industry (string)
	interests (string)
	last_name (string)
	location: (object)
		country: (object)
			code (string)
		name (string)
	network (string)
	url (string)

Profile: (object)
	description (string)
	id (string)
	industry (string)
	name (string)
	network (string)
	website (string)

Profile: (object)
	id (string)
	name (string)
	network (string)

Profile: (object)
	bio (string)
	first_name (string)
	gender (string)
	homeCity (string) 
	id (string)
	last_name (string)
	network (string)

sendassignmentupdates()

Registering this event will let an app get notified of its assignment updates

callback format- a javascript object containing the update information data

{
	action: "ASSIGN"
	errorMessage: ""
	messageId: "123456"
	success: 1
	toMemberId: "123"
	toMemberName: "John Smith"
}

{
	action: "RESOLVED"
	success: 1
	errorMessage: ""
	messageId: "1353547240"
}

OAuth-specific API Functions

These functions are part of the OAuth authentication procedure, as described on the "Authentication process" page.

hsp.editAppAuth()

Displays the authentication popup for the app.