Engagement API

Documentation

The HootSuite Engagement API is located at https://api.hootsuite.com/api/2/

Authentication with the API is based on OAuth 2. Make sure to read the OAuth 2 documentation to learn about how to obtain Access Tokens and how you use them in requests against the API.

Note: While some endpoints don't require user authorization (example: provisioning a new HootSuite member via POST /members), you still need to present a valid Access Token to authenticate your App against the respective endpoint. We suggest you obtain an Access Token using your own member account to represent your App.

messages

The /messages endpoint provides access to HootSuite's rich publishing capabilities. The single POST method enables publishing to multiple social networks with built-in message scheduling and geo-location capabilities.

HTTP Method   Description
POST

Post messages to one or more social networks defined in a HootSuite account. This method provides access to the rich functionality available via the web dashboard, including scheduling, geo-location and posting to multiple networks.

Required Parameters:

  • message: The message to be posted across social networks
  • socialNetworks: An array of HootSuite social network IDs

Optional Parameters:

  • sendLater: Set to 1 to schedule the message to be sent later, otherwise, the message will be sent immediately
  • autoSchedule: Set to 1 to autoschedule the message to be sent later.
  • timestamp: An integer indicating the time the message is to be sent. Uses POSIX time format where the integer specified is the number of seconds since Thursday, January 1, 1970. All values will be rounded up to the nearest 5 minute time interval.
  • sendAlert: Set to 1 to trigger an email notification to the authenticated user's email address when the message is sent
  • replyToId: The ID of the tweet that is being responded to
  • lat: A latitude for geo-coding the message
  • long: A longitude for geo-coding the message
  • placeId: A Twitter place ID with which to associate the message
  • venueId: A Foursquare place ID with which to associate the message
  • privacyOptions: Only for Facebook and Linkedin. A node which keys are types of social networks and the values are nodes that have type, id, name and (optional) global keys. Example: 'privacyOptions': {'FACEBOOK': [{"type":"CUSTOM","id":123,"name":"Close Friends"}]}

Sample Response:

 {
     "results": {
         "sentMessages": [ {
         "socialNetworkId": hootsuite_social_network_id,
         "socialNetworkMessageId": social_network_message_id
         } ]
     }
     "error": {}
 }

Sample Code

cURL 

 curl -i -X POST -H 'Authorization: Bearer vF9dft4qmT' -d '{"message":"MESSAGE","socialNetworks":[12345]}' https://api.hootsuite.com/api/2/messages
PHP 
 $header = array('Authorization: Bearer vF9dft4qmT');
 $curl = curl_init();
 curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
 $data = array(
            'message' => "this is a message",
            'socialNetworks' => array(12345),
 );
 curl_setopt($curl, CURLOPT_POST, true);
 curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($data));
 curl_setopt($curl, CURLOPT_URL, 'https://api.hootsuite.com/api/2/messages');
 curl_exec($curl);
Ruby 
 # require 'rubygems'
 require 'net/https'
 require 'json'
 
 uri = URI.parse("https://api.hootsuite.com/api/2/messages")
 
 http = Net::HTTP.new(uri.host, uri.port)
 http.use_ssl = true
 
 req = {"message" => "this is a message", "socialNetworks" => [12345]}
 
 request = Net::HTTP::Post.new(uri.request_uri, {'Authorization' => 'Bearer vF9dft4qmT'})
 request.body = JSON.generate(req)
 
 response = http.request(request)
 puts response.body
GET

Get messages for a social network by stream type.

Sort order is always reverse chronological, ie. newest first.

Messages from up to 5 streams can also be queried in one request by providing a "streams" array that contains a set of the below parameters for each stream as an array. By default, this will return one JSON object per stream; Using the "interleaved" parameter, you can retrieve messages from all requested streams in one merged result set, ordered reverse chronologically.
See examples below.

Note that the number of streams you can request from this endpoint is limited to 300 per hour (e.g. 300 requests for single streams, or 60 requests for 5 streams at a time).

Required Parameters:

  • socialNetworkId: HootSuite social network ID. The authenticated user needs to have access to it.
  • type: The type of stream:
    • Twitter:
      • HOME: Home feed
      • MENTION: Mentions
      • SENT: Sent messages
      • RETWEETS_OF_ME: Retweets by others of the tweets to this account
    • Facebook:
      • F_HOME_STREAM: Facebook home stream
      • F_WALL: Facebook wall
      • F_PHOTOS: Facebook photos
      • F_VIDEOS: Facebook videos
      • F_EVENTS: Facebook events
      • F_COMMENTS: Facebook comments

Optional Parameters:

  • count: Number of messages to return. Max: 30. Default: 30.
Optional Parameters for Twitter streams:
  • maxId: Return only messages with IDs lower than maxId (exclusive). Useful for pagination and infinite scrolling.
  • minId: Return only messages with IDs higher than minId (exclusive). Useful to check for new messages.
Optional Parameters for Facebook streams:
  • maxTimestamp: Return only messages with a "created" timestamp lower than maxTimestamp (exclusive). Useful for pagination and infinite scrolling.
  • minTimestamp: Return only messages with a "created" timestamp higher than minTimestamp (exclusive). Useful to check for new messages.

Notes:
  • min and max filters cannot be used together
  • minId and minTimestamp only have an effect if the result contains message IDs (Twitter) or timestamps (Facebook) that match or go below minId/minTimestamp before this filter is applied. A Twitter stream example of when providing minId has no effect would be: minId is the only optional filter you provide, and there are more than 30 messages that are more recent than minId => result gets trimmed to 30 before even reaching minId.
1. Sample response for simple request:

 {
     "request": "\/api\/2\/messages?socialNetworkId=12345&type=HOME&count=2",
     "results": [
         {
             "truncated": false,
             "created_at": "Apr 04 12:00:32 2012",
             "coordinates": null,
             "retweeted": false,
             "place": null,
             "in_reply_to_screen_name": null,
             "contributors": null,
             "user": {
                 "id": 17093617,
                 "profile_image_url": "http:\/\/a0.twimg.com\/profile_images\/1980112209\/Normal-icon_normal.png",
                 "name": "HootSuite",
                 "url": "http:\/\/www.hootsuite.com",
                 "following": true,
                 "screen_name": "hootsuite"
             },
             "retweet_count": 90,
             "favorited": false,
             "in_reply_to_user_id": null,
             "source": "<a href=\"http:\/\/www.hootsuite.com\" rel=\"nofollow\">HootSuite<\/a>",
             "geo": null,
             "in_reply_to_status_id": null,
             "id": 187509958806470656,
             "text": "Is your #Facebook Brand Page optimized? Learn handy #timeline tips in a
                      new @HootSuite_U Lecture: http:\/\/t.co\/OHaUwBIk"
         },
         {
             ...same format as above
         }
     ],
     "error": {}
 }

2. Sample request for multiple streams:

 streams[0][socialNetworkId]=12345
 &streams[0][type]=HOME
 &streams[0][count]=2
 &streams[1][socialNetworkId]=12345
 &streams[1][type]=MENTION
 &streams[1][count]=2

Returns:

An array of objects: One per stream, containing the requested socialNetworkId and type, and an array of the returned messages.

Sample Response:

 {
     "request": "\/api\/2\/messages",
     "results": [
         {
             "socialNetworkId": 12345,
             "type": "HOME",
             "messages": [
                 {
                     "in_reply_to_screen_name": null,
                     "favorited": false,
                     "in_reply_to_user_id": null,
                     "place": null,
                     "geo": null,
                     "in_reply_to_status_id": null,
                     "created_at": "Apr 04 12:00:32 2012",
                     "retweet_count": 90,
                     "user": {
                         "id": 17093617,
                         "url": "http:\/\/www.hootsuite.com",
                         "screen_name": "hootsuite",
                         "name": "HootSuite",
                         "profile_image_url": "http:\/\/a0.twimg.com\/profile_images\/1980112209\/Normal-icon_normal.png",
                         "following": true
                     },
                     "truncated": false,
                     "coordinates": null,
                     "retweeted": false,
                     "source": "<a href=\"http:\/\/www.hootsuite.com\" rel=\"nofollow\">HootSuite<\/a>",
                     "id": 187509958806470656,
                     "contributors": null,
                     "text": "Is your #Facebook Brand Page optimized? Learn handy #timeline tips in a
                              new @HootSuite_U Lecture: http:\/\/t.co\/OHaUwBIk"
                 },
                 {
                     ...same format as above
                 }
             ]
         },
         {
             "socialNetworkId": 12345,
             "type": "MENTION",
             "messages": [
                 {
                     ...same format as above
                 },
                 {
                     ...same format as above
                 }
             ]
         }
     ],
     "error": {}
 }

3. Sample request for multiple streams, interleaved:

 interleaved=1
 &streams[0][socialNetworkId]=12345
 &streams[0][type]=HOME
 &streams[0][count]=2
 &streams[1][socialNetworkId]=12345
 &streams[1][type]=MENTION
 &streams[1][count]=2

Returns:

An array of messages in the same format as with a simple request (see example above).

Sample Code

cURL 

 curl -i -G -H 'Authorization: Bearer vF9dft4qmT' -d "socialNetworkId=12345&type=HOME" https://api.hootsuite.com/api/2/messages
PHP 
 $header = array('Authorization: Bearer vF9dft4qmT');
 $curl = curl_init();
 curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
 curl_setopt($curl, CURLOPT_POST, false);
 curl_setopt($curl, CURLOPT_URL, 'https://api.hootsuite.com/api/2/messages/socialNetworkId=12345&type=HOME');
 curl_exec($curl);
Ruby 
 # require 'rubygems'
 require 'net/https'
 require 'json'
 
 uri = URI.parse("https://api.hootsuite.com/api/2/messages?socialNetworkId=12345&type=HOME")
 
 http = Net::HTTP.new(uri.host, uri.port)
 http.use_ssl = true
 
 request = Net::HTTP::Get.new(uri.request_uri, {'Authorization' => 'Bearer vF9dft4qmT'})
 
 response = http.request(request)
 puts response.body

API Endpoints

Engagement API

Questions? Feedback?

From the HootSuite Blog

Thumbnail for 8 Tips for Social Business, Part 6: Secure

8 Tips for Social Business, Part 6: Secure

Social media blunders make headlines, and these headlines make business executives nervous. We’ve all seen...
Read More

Thumbnail for Join us for Live Social Media Q&A with UK Minister, Vancouver Mayor

Join us for Live Social Media Q&A with UK Minister, Vancouver Mayor

A growing number of governments, from municipal to federal, are increasing their engagement through social...
Read More

Thumbnail for Big Global Social Networks Are Closing In On Facebook

Big Global Social Networks Are Closing In On Facebook

by Ryan Holmes, HootSuite CEO  Last year, Facebook marked a new milestone in its nine-year history. It...
Read More

Thumbnail for A Wiggly for Wednesday ~ Ultra Magnus

A Wiggly for Wednesday ~ Ultra Magnus

Ahhh, Wednesday again… which means another wonderful wiggly gif! HootSuite’s Greg Williams -aka gwilli- has thousands of these ‘wiggly’ images...
Read More