This post will show you the options for getting presence information (Online Now status) from the Yammer REST API.
Overview
The Online Now feature of Yammer is driven by Yammer’s own REST API. In this post, I’ll show you the calls available to get presence information for use in your own applications.
Some parameters and endpoints shown below are not officially documented by Yammer – expect that these may change at any time.
The AutoComplete API
The AutoComplete endpoint has an undocumented parameter, presence=true, that you can use to get presence information for particular users.
The AutoComplete api is used to provide type-ahead for searches, #hashtags, and @mentions, but is also a great way to quickly get detailed user information. To get the presence information for a specific user, you can use the short username and pass it in as the prefix parameter.
|
1 |
https://www.yammer.com/api/v1/autocomplete/ranked?prefix=[shortusername]&models=user:5&presence=true |
5/1/2014 – REST APIs accessed through the JS SDK should use the https://api.yammer.com/api/v1 url instead of https://www.yammer.com/api/v1. The AutoComplete api is currently an exception however, and will only respond to https://www.yammer.com/api/v1/autocomplete/ranked
Autocomplete doesn’t guarantee an exact match with users (it won’t match an email address or user id), so be sure you request more than one result, and inspect the length/count of objects returned to make sure you find the right one.
If you want to get a bunch of users, you can leave the prefix empty and specify a large number:
|
1 |
https://www.yammer.com/api/v1/autocomplete/ranked?prefix=&models=user:50&presence=true |
If you want to get the same list of users that appears in the Online Now box on the Yammer web site, you can use another undocumented parameter: secondOrderRanks=true. You will most likely want to use this with the includePendingUsers=false parameter as well:
|
1 |
https://www.yammer.com/api/v1/autocomplete/ranked?prefix=&models=user:50&presence=true&secondOrderRanks=true&includePendingUsers=false |
Any of the variations above will return a JSON object with a presence property. Values are “online”, “offline”, “idle”, and “mobile”.
The Users API
The Users API is another endpoint you can use to get presence information. Many of the user endpoints will honor an undocumented parameter, include_presence=true.
The User API calls that currently work with the include_presence parameter are:
|
1 |
https://api.yammer.com/api/v1/users.json?include_presence=true |
|
1 |
https://www.yammer.com/api/v1/users/current.json?include_presence=true |
|
1 |
https://www.yammer.com/api/v1/users/[:id].json?include_presence=true |
The include_presence parameter does not work with the following User API calls:
|
1 |
https://www.yammer.com/api/v1/users/by_email.json?email=[:email] |
|
1 |
https://www.yammer.com/api/v1/users/in_group/[:id] |
Search
The search api doesn’t seem to return presence at this time.
Whoville – Getting and Updating Status
Another undocumented API endpoint Yammer internally uses to get and set status is /api/v1/whoville. Unfortunately you can’t access this from the Javascript SDK (the endpoint throws Access-Control-Allow-Origin errors in the browser, and I suspect that it is only wired to work with requests from an Origin of www.yammer.com).
A typical GET request for status looks like the following:
|
1 |
https://www.yammer.com/api/v1/whoville/presence/networks/[:id]/users/[:id],[:id],[:id] |
You can request the status for multiple users (separated with commas), and it will return JSON similar to the following:
|
1 2 3 4 5 6 7 8 9 10 |
{ "presence": [ { "state":"ONLINE", "user_id":123456789, "client_application_id":1 } ] } |
This is the endpoint that the Yammer web UI uses to periodically poll for status changes.
To update status, Yammer internally uses another endpoint:
|
1 |
https://www.yammer.com/api/v1/whoville/networks/[:id]/users/[:id]/online |
Calling this endpoint with an HTTP POST will update the user’s status to ONLINE. I’ve tried experimenting with different parameters at the end, such as /idle, /mobile, and /offline, but the only one that I was able to use to any effect was /online.
To call this endpoint, it appears you need to have Accept: */* and Content-Type: application/json in your request headers. It also only appears to be able to update the current user’s status (I haven’t tried it with a verified admin token).
Summary
Hopefully this brief tour of the Presence options in the Yammer API gives you some ideas to start thinking about integrating Yammer Presence in your applications. And hopefully the API matures a bit and becomes officially supported and with more features.
Great article.
I’m trying to use the the autocomplete functionality and had it working at one time. Since the new API that was introduced in April, I’ve been getting same origin policy errors on this function only. I believe it has something to do with using the old URLs. Do you have any advice on how to get around this?
Thanks.
Hi Jason,
Try to use the full old url for the autocomplete endpoint for now (https://www.yammer.com/api/v1/autocomplete/ranked), and the new url for all your other api calls. At least until they provide a fix.
The REST API, does not support Yammer/Sharepoint SSO correct?