Introducing the Interaction History API

about a year ago by Josh Brown

Today, we’re excited to launch the Interaction History API — a new way for third-party apps to fetch social engagement data from Hootsuite.

The Interaction History API allows Hootsuite Enterprise customers to read mentions, comments, likes, and other interactions between their organization and another social media profile. Developers can now build smarter Hootsuite apps, giving Hootsuite users context on the social relationships they’re building with their customers on social media.

You can use the Interaction History API in an app for the Hootsuite app directory or in an app that is custom-built for a specific Hootsuite Enterprise organization. It’s perfect for apps that rely on sentiment analysis and apps that connect with CRM solutions. For example, you can use the Interaction History API to create a stream plugin that provides insights on past tweets from a user who mentioned you, like the topics of posts they usually engage with:

Interaction history data is also useful when building an integration between Hootsuite and marketing automation platforms like Marketo. Engagements fetched through the API can be used to inform lead-scoring and lead-segmentation programs that drive other marketing campaigns.

Using the Interaction History API

The Interaction History API provides developers with two new read endpoints:
GET /v1/interactions/twitter
GET /v1/interactions/facebook

Making calls to the Interaction History API is easy. Like other Hootsuite APIs, users will authorize your app to access their organization through OAuth 2.0. After the user installs your app you will be able to obtain an access token that can be used to request Interaction History information. You can find a sample HTTP request below along with code samples for PHP and Node.js:

<?php
$params = array(
	'socialNetworkId' => 2232056052, // profile linked to your Hootsuite account 
	'targetSocialNetworkId' => 2232056052 // profile of a user you've interacted with
 );
$url = "https://platform.hootsuite.com/v1/interactions/twitter?" . http_build_query($params);
$ch = curl_init(); 
curl_setopt($ch, CURLOPT_URL, $url); 
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer ' . $token));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); 
$response = curl_exec($ch);
var request = require('request');
request.get({
    'uri': 'https://apis.hootsuite.com/v1/interactions/twitter',
    'auth': {
      'bearer': hootsuiteAccessToken
    },
    'qs': {
      'socialNetworkId': 2232056052,
      'targetSocialNetworkId': 2232056052 
    }
  },
function (error, response, body) {
  // do something cool with the data here
  }
);
GET /v1/interactions/twitter?socialNetworkId=2232056052&targetSocialNetworkId=2232056052 HTTP/1.1
Host: apis.hootsuite.com
Authorization: Bearer {{ token }}

Examples of the response data can be found in the Hootsuite API reference documentation. At the moment, the Interaction History API is limited to interactions with Facebook and Twitter.

Supplementing the interaction data

The Interaction History API allows your app to see the type of each interaction (e.g. MENTION or PRIVATE_MESSAGE), and the network ID of the associated message. Many apps may need more information, such as the message body or the location of the user. You can use the APIs of Facebook and Twitter to boost Hootsuite’s interaction history data and create extra insights that would not be available from the Hootsuite API alone.

For more information, see the API documentation for Twitter and for Facebook, or check out our sample plugin on GitHub for an example of supplementing status data from Twitter.

Get started

Before you can use the Interaction History API you will need to have a Hootsuite app with an API client ID and secret. If you don’t have a Hootsuite developers account, sign up for one here. After you register your first app, send an email to [email protected] We’ll provision your app with a client ID and secret that you can use to access the Interaction History API.

Have questions about the new API? Drop by the Hootsuite developer forums and let us know. We can’t wait to see what you build!