1 Sysomos API Documentation, Updated February 2014
Heartbeat API Documentation Sysomos Inc., Marketwired. Revised: February 2014
2 Sysomos API Documentation, Updated February 2014
Preface
Heartbeat provides several REST based APIs through which collected information can be retrieved in XML
format. Data returned via XML can be used by clients to build customized dashboards, integrate Sysomos
heartbeat data within their CRM systems or design applications & dashboards that could work on the API data
from their respective heartbeat accounts. We currently do not provide development services for integrating our
API’s within client’s existing applications. All our major clients use their in-house or contracted development
teams for their development projects feeding data from their heartbeat accounts.
For most of your needs concerning heartbeat data and analytics on your heartbeat data, Measure API
and RSS Content API will suffice. Sysomos however does provide additional APIs to return data related to
Influencers, Content, Buzzgraph and Info. We also provide write API functionality to enable clients to interact
directly to their heartbeat data via API and Widget options for them to be able to use Sysomos’ analytics directly
as widgets as detailed in this document.
Volume of API calls to client heartbeats is administrated by a fair use policy of allowing 1500 API calls
per day. Each API call can provide up to 500 mention results; thus 1500 API calls can deliver up to a maximum of
720,000 social media mentions per day. This suffices most data needs given the average daily volume of new
data in all Sysomos heartbeats is significantly less than 100,000 mentions per day. For e.g. if your heartbeat gets
50,000 new mentions per day & known that every API call returns up to 500 results, you would only need 100
API calls (50000 / 500 = 100) to fetch all the 50,000 mentions including any social metadata (demographics,
sentiment, authority etc.) associated with the mentions via RSS Content API. For higher API call needs, please
reach sales for pricing.
API access comes at an additional API licensing cost, for details contact your Account Executive or Sales
at Sysomos. Sysomos provides demo access to API for a charge free period of 2 weeks, which is extendible at
Sysomos’ discretion if there is a genuine business need for extended trial. Sysomos Client Success Managers
and/or Social Media Specialists are the first point of contact for any API related inquiries. Feel free to reach them
for any questions or concerns about our API capabilities and how they can be best used to serve your business
needs.
3 Sysomos API Documentation, Updated February 2014
Index
TITLE PAGE
1 HEARTBEAT MEASURE API 4
2 HEARTBEAT RSS CONTENT API 7
3 OTHER APIS
HEARTBEAT INFLUENCER API
11
HEARTBEAT CONTENT API 14
HEARTBEAT BUZZGRAPH API 16
HEARTBEAT WORDCLOUD API 19
HEARTBEAT INFO API 21
4 ENGAGEMENT APIS 23
5 WIDGETS 28
6 CONTACT US 30
4 Sysomos API Documentation, Updated February 2014
Heartbeat Measure API
This API provides the raw numbers and counts as presented in the Measure tab of Heartbeat.
The format of the URL is:
(i) the API key (ii) the Heartbeat ID, (iii) the date range (iv) a list of filters, and optionally (v) a list of tags required in the output.
Important Note: The part of the URL with the date range and list of filters is exactly the same as in the web user interface for the Heartbeat’s Measure tab. The easiest way to produce this part of the url is to login to the web UI, navigate to the Measure tab, select the list of filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.
URL Parameter
Explanation
apiKey API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.
sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.
cTs Comma separated list of tags to be included in the output. The tag name is in the same format as in fTs and hence the web UI can be used to find the tag names. Simply use the tag as filter on the Measure tab and copy it from the fTs parameter of the URL.
5 Sysomos API Documentation, Updated February 2014
Example 1:
http://api.sysomos.com/v1/heartbeat/measure?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&cTs=~SENTIMENT~pos,~SENTIMENT~neg,~SENTIMENT~none
The URL above uses a 7 day period (dRg) with the filter tag (fTs) equal to “me”. The same set of filters is used on the following web UI page:
http://hb.sysomos.com/hb2/?hid=<YOUR-HEARTBEAT-ID>&tab=statistics&dRg=7&fTs=me
The list of tags included in the output are ~SENTIMENT~pos , ~SENTIMENT~neg, and ~SENTIMENT~none which are for Positive, Negative and No sentiment. This will produce output similar to:
6 Sysomos API Documentation, Updated February 2014
Example 2:
http://api.sysomos.com/v1/heartbeat/measure?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&sDy=2010-10-07&eDy=2010-10-08&fTs=dunkin-coffee,promotion,~COUNTRY~US,~SOURCE~t&cTs=dunkin-coffee,promotion
The URL above uses the period between October 7th 2010 (sDy) and October 8th 2010 (eDy) with the filter tag (fTs) equal to dunkin-coffee, promotion, ~COUNTRY~US and ~SOURCE~t. The same set of filters is used on the following web UI page:
http://hb.sysomos.com/hb2/?hid=<YOUR-HEARTBEAT-ID>&tab=statistics&fTs=dunkin-coffee,promotion,~COUNTRY~US,~SOURCE~t&sDy=2010-10-07&eDy=2010-10-08
The tags included in the output are dunkin-coffee and promotion which are defined as custom tags in this Heartbeat. This will produce output similar to:
7 Sysomos API Documentation, Updated February 2014
Heartbeat RSS Content API
As with the Content API, this API returns content information for the mentions collected by Heartbeat.
The format of the URL is:
(i) the API key,
(ii) the Heartbeat ID,
(iii) the date range,
(iv) a list of filters, and optionally
(v) a list of tags required in the output.
The part of the URL with the date range and list of filters is exactly the same as in the web user interface for the Heartbeat’s Measure tab. The easiest way to produce this part of the url is to login to the web UI, navigate to the Measure tab, select the list of filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.
URL Parameter
Explanation
apiKey
API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.
sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the
8 Sysomos API Documentation, Updated February 2014
URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.
cTs Comma separated list of tags to be included in the output. The tag name is in the same format as in fTs and hence the web UI can be used to find the tag names. Simply use the tag as filter on the Measure tab and copy it from the fTs parameter of the URL.
startid A 0-based integer index specifying the initial record to retrieve in the result set. In conjunction with the max parameter, can be used to batch results for a given query.
max The maximum number of records to retrieve.
Example:
http://api.sysomos.com/v1/heartbeat/rsscontent?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&cTs=~SENTIMENT~pos,~SENTIMENT~neg,~SENTIMENT~none&startid=0&max=10
Output:
NOTE: For Twitter no data is provided in the Title and Content XML Tags i.e. the raw text for the tweet. Tweet ID,
Tweet Web URL and Twitter API URL are provided that can be used to fetch that data directly from twitter.
<beatApi xmlns="http://www.blogscope.net/api/namespace/schema/SearchResponse">
<beatRequest>
<heatbeatID>3692</heatbeatID>
<key>YOUR API KEY</key>
<size>1</size>
<offset>0</offset>
</beatRequest>
<beatResponse>
<totalResults>91542</totalResults>
<beat>
<docid>3692:10532076</docid>
<mediaType>TWITTER</mediaType>
<time>2012-08-16T12:04:07-04:00</time>
<title>tweet</title>
<content>http://hb.sysomos.com/hb2/sidebar/?hid=3692&bid=10532076</content>
9 Sysomos API Documentation, Updated February 2014
<link>http://hb.sysomos.com/hb2/sidebar/?hid=3692&bid=10532076</link>
<location>
<country>th</country>
<locationString>chiangrai-;thailand-?</locationString>
</location>
<influenceLevel>6</influenceLevel>
<sentiment>NONE</sentiment>
<tag>
<value>t</value>
<displayName>TWITTER</displayName>
<systemType>SOURCE</systemType>
</tag>
<tag>
<value>-1</value>
<displayName>-1</displayName>
<systemType>AGE</systemType>
</tag>
<tag>
<value>none+</value>
<displayName>Not Assigned</displayName>
<systemType>ASSIGNED</systemType>
</tag>
<tag>
<value>none</value>
<displayName>none</displayName>
<systemType>SENTIMENT</systemType>
</tag>
<tag>
<value>blackberry</value>
<displayName>blackberry</displayName>
</tag>
10 Sysomos API Documentation, Updated February 2014
<tag>
<value>TH</value>
<displayName>Thai</displayName>
<systemType>LANGUAGE</systemType>
</tag>
<tag>
<value>unknown</value>
<displayName>Unknown Gender</displayName>
<systemType>GENDER</systemType>
</tag>
<tag>
<value>1204</value>
<displayName>1204</displayName>
<systemType>T</systemType>
</tag>
<tweetid>236131231568367616</tweetid>
<tweetJsonLink>http://api.twitter.com/1/statuses/show.json?id=236131231568367616
&include_entities=true</tweetJsonLink>
<tweetHbLink>http://hb.sysomos.com/hb2/sidebar/?hid=3692&bid=10532076
</tweetHbLink>
<twitterFollowers>1160</twitterFollowers>
<twitterFollowing>129</twitterFollowing>
</beat>
<count>1</count>
</beatResponse>
</beatApi>
Other APIs Heartbeat Influencer API This API returns the list of influencers as shown in Heartbeat’s Top Influencers tool.
11 Sysomos API Documentation, Updated February 2014
The URL must contain
(i) the API key (ii) the Heartbeat ID (iii) the date range (iv) a list of filters (v) the social media type (vi) and optionally the number of influencers to return (vii) and optionally the number of mentions to return for each influencer
As with the Measure API, the easiest way to produce this part of the URL is to login to the web UI, navigate to the Top Influencer tool, select the source and filters as required, and copy the values of the parameters fTs, dRg, tTb, sDy and eDy as present in the URL.
URL Parameter
Explanation
apiKey API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.
sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.
tTb Type of social media to retrieve top influencers for. The value of this can be ‘blogposts’, ‘twitter’, ‘forums’, or ‘news’. Defaults to ‘twitter’ when not specified.
maxInfluencers The maximum number of influencers to return. The default value is 10.
maxMentions The number of mentions returned for each influencer. A mention contains data for a tweet/post/article produced by the influencer. Default value of 25.
Example 1:
http://api.sysomos.com/dev/v1/heartbeat/influencer?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&tTb=twitter&dRg=7&fTs=me,~SENTIMENT~neg
12 Sysomos API Documentation, Updated February 2014
This URL returns the top influencers for Twitter (tTb) over the last 7 days (dRg) who made comments with negative sentiment regarding the keywords defined in ‘me’ (fTs). It is equivalent the UI page:
http://hb.sysomos.com/hb2/?hid=YOUR-HEARTBEAT-ID&tab=statistics&sTb=influencers&tTb=twitter&dRg=7&fTs=me,~SENTIMENT~neg
The XML response would be similar to the following:
Example 2:
http://api.sysomos.com/dev/v1/heartbeat/influencer?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&tTb=blogposts&sDy=15615&eDy=15617&fTs=me&scO=Recency&maxSample=3000&maxInfluencers=4
This URL returns the top influencers for Blogs (tTb) between October 1st’2012 (sDy) and October 3rd’2012 (eDy) who mentioned the filter ‘tim-hortons’(fTs). It only returns the top four influencers (maxInfluencers). Other than the number of influencers it is equivalent to the UI page:
http://hb.sysomos.com/hb2/?hid=YOUR_HB_ID&startid=0&maxC=6&max=20&tab=statistics&sTb=influencers&tTb=blogposts&sDy=15615&eDy=15617&fTs=me&scO=Recency&maxSample=3000&maxToShow=4
13 Sysomos API Documentation, Updated February 2014
The XML response (tags minimized to show all four influencers):
14 Sysomos API Documentation, Updated February 2014
Heartbeat Content API
In addition to the RSS Content API which allows use of filters, Heartbeat also offers a more low-level content API for mirroring the entire database of social mentions locally. Content API is a legacy version of RSS Content API, it is recommended to use RSS Content API over this API if you are a new client.
The URL requires
(i) the API key and (ii) the Heartbeat ID, and optionally (iii) the start date (iv) the end date (v) the number of mentions to return and (vi) a starting offset
URL Parameter
Explanation
apiKey API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
addedAfter The GMT start date - only content added after this date will be returned. The format of this parameter is yyyy-mm-ddThh:mm:ssZ (e.g. 2010-05-22T16:30:00Z).
addedBefore The GMT end date - only content added before this date will be returned. The format of this parameter is yyyy-mm-ddThh:mm:ssZ (e.g. 2010-05-22T16:30:00Z).
size The number of mentions to return, with 100 being the default. Mentions are returned in chronological order starting with the earliest.
offset The number of mentions to skip in the return. An offset of 10 would mean that the first mention returned is the 11th mention for the specified time period.
Example:
http://api.sysomos.com/dev/v1/heartbeat/content?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&offset=0&size=10&addedAfter=2010-10-15T13:00:00Z&addedBefore=2010-10-18T13:00:00Z
This URL returns content for the period between 1pm GMT, October 15th 2010 (addedAfter) and 1pm GMT, October 18th (addedBefore). The response has 10 mentions (size), starts at the first mention (offset), and looks similar to the below:
15 Sysomos API Documentation, Updated February 2014
16 Sysomos API Documentation, Updated February 2014
Heartbeat Buzzgraph API
This API returns the word-pair metrics associated with Heartbeat’s Buzzgraph tool. If you are primarily interested in the image, we provide a Buzzgraph widget for webpage integration (see Heartbeat Widgets documentation), so you do not need to go through the API and code your own graph.
Similar to the Measure API, the URL must contain
(i) the API key, (ii) the Heartbeat ID, (iii) the date range, (iv) a list of filters, and optionally (v) the number of word pairs to return.
The easiest way to produce this part of the URL is to login to the web UI, navigate to the Buzzgraph tool, select the filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.
URL Parameter
Explanation
apiKey API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.
sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.
size The number of word-pairs to return. The default is 30.
Example:
17 Sysomos API Documentation, Updated February 2014
http://api.sysomos.com/v1/heartbeat/buzzgraph?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=2&fTs=me,~SOURCE~n
This URL returns the Buzzgraph word-pairs for content collected during the last 2 days (dRg) filtered for the tag “me” in news sources (fTs). It is equivalent to the information in the UI page:
http://hb.sysomos.com/hb2/?hid=YOUR-HEARTBEAT-ID&tab=statistics&sTb=analytics&dRg=2&fTs=me,~SOURCE~n
Each word-pair in the XML response includes a number signifying the relative strength of association between those words:
18 Sysomos API Documentation, Updated February 2014
19 Sysomos API Documentation, Updated February 2014
Heartbeat Wordcloud API
This API returns the wordcloud metrics associated with Heartbeat’s wordcloud tool. If you are primarily interested in the image, we provide a wordcloud widget for webpage integration as a link at the bottom of the API returned results, this is a dynamic widget that changes based on the filters.
Similar to the Measure API, the URL must contain
(i) the API key, (ii) the Heartbeat ID, (iii) the date range, (iv) a list of filters, and optionally
The easiest way to produce this part of the URL is to login to the web UI, navigate to the Wordcloud tool, select the filters as required, and copy the values of the parameters fTs, dRg, sDy and eDy as present in the URL.
URL Parameter
Explanation
apiKey API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
dRg Number of days, if the end date is the same as today. Copy this from the web UI of Heartbeat’s measure page after selecting the appropriate data range. Format is simple integer.
sDy Start date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
eDy End date. Use this only when dRg is not used and the end date is not same as today. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting the appropriate data range. Format is like 2010-06-08.
fTs List of filters. Format is comma separated list of the filters you wish to apply. Copy this from the URL on web UI of Heartbeat’s measure tab after selecting appropriate filters from top left.
Example:
20 Sysomos API Documentation, Updated February 2014
http://api.sysomos.com/v1/heartbeat/wordcloud?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&dRg=2&fTs=me,~SOURCE~n
This URL returns the wordcloud words for content collected during the last 2 days (dRg) filtered for the tag “me” in news sources (fTs). It is equivalent to the information in the UI page:
http://hb.sysomos.com/hb2/?hid=YOUR-HEARTBEAT-
ID&tab=statistics&sTb=analytics&dRg=2&fTs=me,~SOURCE~n
21 Sysomos API Documentation, Updated February 2014
Heartbeat Info API
This API returns a Heartbeat's settings, including general settings, queries and tagging rules, user
details (including twitter setup) and configured Facebook pages.
The URL must contain
(I) the API key, and
(II) the Heartbeat ID. The service is located at http://api.sysomos.com/v1/heartbeat/info?
URL Parameter
Explanation
apiKey
API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
Example 1:
http://api.sysomos.com/v1/heartbeat/info?hid=YOUR-HEARTBEAT-ID&apikey=YOUR-APIKEY
22 Sysomos API Documentation, Updated February 2014
23 Sysomos API Documentation, Updated February 2014
Engagement APIs
In addition to the standard read-only REST API, Heartbeat provides a write-access REST-API to affect changes in Heartbeat from an external application.
Currently Heartbeat provides API to:
1. add workflow comments to individual beats 2. to post to walls of Facebook fan pages configured within Heartbeat 3. and to post and reply to status updates of Twitter users configured within Heartbeat
Access to Heartbeat Write APIs must be configured enabled separately from read-only API access. If you receive an “API Access disabled” error message, contact your account manager.
Heartbeat Update Workflow API
This API allows an external application to 1) add a workflow comment to and/or update the workflow status of an existing Beat within a Heartbeat account.
For comments, the user posting the comment is implied by the per-user apiKey parameter.
If status is specified, a comment will automatically be added to the workflow identifying the user to which the post was assigned.
URL Parameter Explanation
apiKey
API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
bid Integer beat id, identifies the post within each Heartbeat account whose workflow you with to update.
status String userid, assigns the post to a user within the Heartbeat workflow. The user must be a valid user in the Heartbeat account identified by hid. The special strings none+ and closed+ may also be specified. These strings set the workflow's assigned status to “Assigned to none” and “Case closed”, respectively.
24 Sysomos API Documentation, Updated February 2014
comment String containing the text of the 'workflow update' comment to add to the Beat.
Example 1:
http://api.sysomos.com/v1/heartbeat/workflow?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&bid=BEAT-ID&comment=this%20is%20a%20comment
Beat ID can be found by hovering over the respective beat when testing this API as shown in red circle below, these are also returned as an XML field of the docID tag in the RSS Content API as:
<docid>YOUR-HEARTBEAT-ID:BEAT-ID</docid>
E.g. <docid>1234:567890</docid>
This URL returns a minimal response echoing the request parameters, with and an Errors element if the operation fails.
The XML response is as follows:
<hbWorkflowApi>
<request>
<hid>YOUR-HEARTBEAT-ID</hid>
<bid>YOUR-BEAT-ID</bid>
<status>[email protected]</status>
</request>
</hbWorkflowApi>
In case of error the response will contain an error TAG defining the error, contact your account manager in that case.
Example 2:
25 Sysomos API Documentation, Updated February 2014
http://api.sysomos.com/v1/heartbeat/workflow?apiKey=YOUR-APIKEY&hid=YOUR-HEARTBEAT-ID&bid=YOUR-BEAT-ID&comment=this%20is%20a%20comment
The following XML indicates a failure, in this instance; the bid parameter does not refer to a Beat in the Heartbeat account. The error element will be set to true if an internal error has occurred – the element is false in this case since the error is due to invalid input. Is a comment
Example 3:
http://api.sysomos.com/v1/heartbeat/workflow?apiKey=APIKEY&hid=496&bid=YOUR-BEAT-ID&[email protected]
This request assigns a post within Heartbeat to the user ‘[email protected]’. As with manual workflow assignment in Heartbeat, the user being assigned the post will receive a workflow email if the user’s email address is configured within Heartbeat.
Heartbeat Post to Twitter/Facebook API
This API allows an external application the ability to post messages to external platforms. We currently support Twitter status updates and Facebook wall posts.
For Facebook wall posts, the Facebook page must be configured within Heartbeat for the Heartbeat account specified by the hid parameter.
If the bid(beat ID) parameter is provided, and refers to a Facebook wall post, the message is posted as a comment to an existing wall post specified by the bid. Posting a reply to a non-public wall will result in an error response from the API.
If no bid parameter is defined, a new wall post referenced by the pageId parameter. Upon successful posting, the post identified by bid will be updated with a workflow comment stating ‘Replied via facebook’.
Twitter accounts must be configured within Heartbeat for the user specified by the apiKey parameter.
26 Sysomos API Documentation, Updated February 2014
As with posting to facebook, if a bid parameter is provided, and refers to a tweet, the message will be posted as a public reply to that tweet. Replies will be prefixed by a @screenname preamble indicating the Twitter user being replied to, if not already in the reply text.
A workflow comment will be added to the post identified by bid stating ‘Replied via twitter as @screenname’. If the bid parameter is omitted, a new tweet is posted.
Twitter direct (private) messaging is supported via the ‘d’ notation: d screenname message. See http://support.twitter.com/entries/14606-what-is-a-direct-message-dm for more details. Note that you can only send direct messages to users that are following the user specified by the screenName parameter.
URL Parameter
Explanation
apiKey
API Key
hid Integer heartbeat id, unique for each Heartbeat account. Copy this from the url on the web UI of the Heartbeat account after navigating to the Measure page.
Bid Integer beat id, identifies the post within the Heartbeat account to reply to. If not provided, a new wall post (Facebook) or status update (Twitter) is created.
Platform The social media platform on which to post. Supported values are twitter and facebook. If Bid is provided, the platform parameter is optional – if not provided it will be inferred from the type of post referred to by bid.
screenName The screen name of the Twitter user whose status should be updated. Do not include the leading @. This twitter user must be configured in Heartbeat by the user specified by the apiKey parameter.
pageId The pageId of the facebook page to post to. The parameter is only relevant if the platform element is set to facebook. The page referenced by this pageId must be configured within Heartbeat.
message String containing the message text to post. If platform is set to twitter, this field is limited to 140 characters.
Example 1 (Facebook):
http://api.sysomos.com/dev/v1/heartbeat/post?apiKey=<YOUR-APIKEY>&hid=<YOUR-HEARTBEAT-ID>&platform=facebook&message=I'm%20on%20facebook&pageId=<YOUR-FACEBOOK-PAGE-ID>
27 Sysomos API Documentation, Updated February 2014
Example 2 (Twitter):
http://api.sysomos.com/dev/v1/heartbeat/post?apiKey=<YOUR-APIKEY>&hid=<YOUR-HEARTBEAT-ID>&platform=twitter&message=%23winning&screenName=sysomos
28 Sysomos API Documentation, Updated February 2014
Heartbeat Widgets
Heartbeat provides several ways of integrating it with other business applications:
Password-less logins: Users can navigate from any web app to Heartbeat with a single click requiring no
passwords or additional authentication steps.
Data Exports: All content monitored by Heartbeat can be periodically exported as either RSS XML or CSV
Widgets: Heartbeat charts and data can be embedded in another web app within minutes by including it
as an iframe or image. All widgets provide password-less click through for detailed data drill down.
REST Based Measure API: For a tighter integration, XML-based REST APIs are available.
Example Widget 1: Latest Activity
29 Sysomos API Documentation, Updated February 2014
The activity chart in your Heartbeat can be integrated as an iframe in your web application by using the following URL. Note the APIKEY needs to be substituted with the correct value.
http://hb.sysomos.com/hb2/widgets/measure.jsp?hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&scO=date&authStr=YOUR-APIKEY
Example Widget 2: BuzzGraph
The BuzzGraph shows a visual summary of conversations by listing relevant keywords.
The BuzzGraph can be included as an image by using the URL below. Note the APIKEY needs to be substituted with correct value. This widget is not an iframe but an img.
http://hb.sysomos.com/hb2/dimg/buzzgraphhbimg.jsp?hid=YOUR-HEARTBEAT-ID&dRg=7&fTs=me&width=450&sisi=30&kt=1&authStr=YOUR-APIKEY
30 Sysomos API Documentation, Updated February 2014
Contact Us To have any more questions concerning Sysomos, feel free to reach your respective Account Manager or Sales representative. Call: 1 866 483 3338 Email: [email protected]
Technical Support [email protected]
Sysomos Inc. 25 York Street, Suite 900, P.O. Box 403 Toronto, ON, M5J 2V5, Canada See on Google maps 1 416 479 0629 (Phone) 1 866 961 4978 (Fax)
Media Inquiries [email protected] blog.sysomos.com twitter.com/sysomos
Privacy Inquiries [email protected]
Sales/General Inquiries [email protected]
Top Related