Ask Yammer

Yammer API Primer

ablaine — Tue, 05 Sep 2017 15:08:50 GMT

While most day to day tasks can be accomplished in the Yammer web app, utilizing our APIs can open up administrative and automation options previously very time consuming. If you’ve never worked with an API before, this can seem like a daunting task. With this article, I hope to demystify APIs and illustrate how anyone can utilize them to perform tasks like obtaining, posting, and deleting messages.

Parts of an API call

There are 3 main parts of an API call:

The endpoint URL. A list of our supported API endpoints, their URLs and the input they take can be found at https://developer.yammer.com/docs/rest-api-rate-limits.
The authorization headers – This is akin to logging into the API. It tells the API who is making the call and that you’re authorized to make those calls.
Any data passed to that API endpoint – For example a user id or a page number. Each endpoint’s documentation will describe the data it can consume when generating its output.

Authorizing an API call

Every API call must be authorized before it will return data. To authorize an API call, an authorization header with the OAuth token is sent stating who is making the call. To obtain this OAuth token, first register an app in Yammer, detailed at https://developer.yammer.com/docs/app-registration. If you are unsure what to put as the Website and Redirect URI, just put an https:// address to your company’s website for the time being. Once the app is registered, click “Generate a developer token for this application” and save this OAuth token. It will be used it to authorize your API calls and won’t expire until something is explicitly done to revoke it. [caption id="attachment_465" align="alignnone" width="485"] App Registration[/caption] [caption id="attachment_475" align="alignnone" width="457"] Obtaining an OAuth token[/caption] Once you have obtained this OAuth token, you need to pass it to the API in a header. This header looks like “Authorization: Bearer OAUTH_TOKEN” in plain text, but an example of passing this in PowerShell can be found below.

Using PowerShell to call Yammer APIs

To make API calls in PowerShell, the Invoke-RestMethod cmdlet documented at https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod?view=powershell-5.1 will be used. Here is a sample script that calls the messages.json endpoint and dumps its response: its response:

$uri = "https://www.yammer.com/api/v1/messages.json"
$token = "YOUR_OAUTH_TOKEN_HERE"
$headers = @{ "Authorization" = "Bearer " + $token }
$response = Invoke-RestMethod -Method Get -Uri $uri -Header $headers
Write-Output $response

Passing data to an API endpoint

There are 3 main ways to pass data to an API endpoint.

In the endpoint, itself. For example, to get info on a user by their user_id (documented at https://developer.yammer.com/docs/usersidjson), you call the endpoint https://www.yammer.com/api/v1/users/186029475.json where 186029475 is the user_id
In query string variables, like page numbers. From https://developer.yammer.com/docs/usersin_groupidjson, this might look like https://www.yammer.com/api/v1/users/in_group/5678.json?page=2 where the ? separates the endpoint URL from its query string variables. To pass multiple variables, you separate them with an & like https://www.yammer.com/api/v1/users/in_group/5678.json?page=2&reverse=TRUE
In the body of the message, specifically when using the POST method

For 1 and 2 above, you change nothing about your API calls except the actual URL you pass. 3 is a little more complicated and I’ll illustrate its use with an example. In this example, you will be posting a message to a specific group. You’ll need a group_id to do this and you can locate one by navigating to a group in Yammer and look for the “feedId=####” in the URL and the #### is your group_id.

POST in PowerShell

To POST data to an API, information like the body of the message and the group to post into must be sent to the API. In this example, a format called json (JavaScript Object Notation) is used to pass this data. First, the content-type header stating the data is being sent as json is added. Next, a $jsonbody variable is created to hold the json data. The -Method Post is used instead of Get and add the -Body $jsonbody is added to the Invoke-RestMethod call.

$uri = "https://www.yammer.com/api/v1/messages.json"
$token = "YOUR_OAUTH_TOKEN"

$headers = @{
"Authorization" = "Bearer " + $token
"content-type" = "application/json"
}

$jsonbody = '{
"body": "Hello World!",
"group_id": 8510571
}'

$response = Invoke-RestMethod -Method Post -Uri $uri -Header $headers -Body $jsonbody

You could also pass the body data as unencoded text in which case you would change the content-type and body. This would look like:

$uri = "https://www.yammer.com/api/v1/messages.json"
$token = "YOUR_OAUTH_TOKEN"

$headers = @{
"Authorization" = "Bearer " + $token
"content-type" = " application/x-www-form-urlencoded"
}

$formbody = “body=Hello+World!&group_id=8510871”
$response = Invoke-RestMethod -Method Post -Uri $uri -Header $headers -Body $formbody

Deleting in PowerShell

Just like creating and reading resources via our API, messages can be deleted by users authorized to do so. Users are authorized to delete their own messages, group admins are authorized to delete messages in groups where they’re an admin, and verified admins can delete any posts they can see (Note: For Verified Admins to delete messages in private groups / messages to which they don’t belong, they must first enable Private Content Mode). In this example you will be deleting a message with a specific ID (1234) as documented at https://developer.yammer.com/docs/messagesid. You’ll need the specific message ID to be deleted which is most often found in a Data Export. The biggest change you’ll notice is the -Method changes to “Delete”.

$uri = "https://www.yammer.com/api/v1/messages/1234"
$token = "YOUR_OAUTH_TOKEN"
$headers = @{ "Authorization" = "Bearer " + $token }
$response = Invoke-RestMethod -Method Delete -Uri $uri -Header $headers

Troubleshooting

When API calls don’t give the expected results, the two best troubleshooting resources available are Fiddler and the Yammer Developer Center. If you haven’t installed Fiddler already, you can obtain it from https://telerik.com/download/fiddler. To start, open Fiddler and hit F12 (or click “Capturing” in the bottom left of the window) to make it stop capturing traffic in the left pane. Duplicate the failing API call in the Fiddler Composer and execute it: [caption id="attachment_476" align="alignnone" width="1061"] Get Example[/caption] [caption id="attachment_485" align="alignnone" width="604"] Post Example[/caption] Double click the line that is generated in the left pane (the API call’s “session” in Fiddler) and the inspectors will show up: Make sure Headers is clicked on the bottom pane and review the response code and reason listed under Response Headers:

“HTTP/1.1 401 Unauthorized” could indicate either your OAuth token is invalid or you’re trying to do something you’re not allowed to do (like post to a private group to which you don’t belong)
“HTTP/1.1 403 Forbidden” could indicate you’re making calls from a blacklisted IP address
“HTTP/1.1 400 Bad Request” indicates the request isn’t formatted properly. For example, if the content-type header is missing when posting a message
“HTTP/1.1 500 Internal Server Error” indicates you sent something in the API request that Yammer didn’t know how to handle

Once you’ve made sure you’re authorized to perform the action you’re trying to perform, the next step is to make sure you’ve formatted your API call properly. For this, head to the Yammer Developer Center at https://developer.yammer.com/docs/rest-api-rate-limits and find the API being used. As an example, let’s pretend you don’t know how to post a message to a group (which was covered above). Note that when creating a resource (like a new post in Yammer), you use the POST method so find the POST message endpoint page located at https://developer.yammer.com/docs/messages-json-post and scroll to the bottom where it says Try It Out. You know the body is going to be “Hello World!” and the group is going to be 8510571, so input that into the form and click Try It! (you might first have to authorize the Yammer Developer Center app on your Yammer account): It will then show you the exact request that was made to the API and the response. The relevant part of this is shown here: You’ll note that things like the Accept, accept-encoding, content-length, and direct_to_user_ids get added automatically. You don’t have to add these to your call to be successful but adding them for good measure is still a good idea. Compare these values to what you’re passing in your code and see what is different. If you’re unable to identify the problem, open a support case for further assistance. You also see that the status code for a successful call is 201 Created. You won’t use this in your call, but you can use that to test for a successful call in your code.

Next Steps

Armed with these tools, you should be able to implement things otherwise not possible like implementing a data retention policy where every month you check for messages that fit some specific criteria (for instance if they are more than a year old) and purge them based on your security needs. A “reply bot” could also be implemented that watches a group and automatically replies to new posts based on your own criteria. If you have a customer support group and see people frequently posting without ticket numbers, you could have the reply bot check for that and reply if it doesn’t find a valid number letting them know what they’ve missed. When designing these apps, part of the difficulty is identifying the correct endpoints to do what you need. The only endpoints Yammer supports are listed at https://developer.yammer.com/docs/rest-api-rate-limits so I’ll look through that list to find what I need. For example, if I wanted to leave a group, I’d look for group based endpoints. I see GET /messages/in_group/…, POST /group_memberships.json, DELETE /group_memberships.json, and GET /users/in_group/… Based on those group endpoints, you could deduce if you want to delete your membership to a group, you’d use the DELETE /group_memberships.json endpoint. Looking at its documentation at https://developer.yammer.com/docs/group_membershipsjsongroup_idid-1, you’ll see it leaves a group. I’ll be writing more blog posts with ideas and examples of how to implement our APIs to perform specific tasks, so stay tuned for those as well.

About the Author

Alex Blaine is a Support Escalation Engineer and code monkey on the Yammer Support Escalation team.

Preauthorizing the Yammer JS SDK

ablaine — Fri, 04 Nov 2016 05:05:54 GMT

Under normal circumstances, users will have to create a Yammer session before using the JS SDK in scenarios like apps integrated on intranet pages. If you’re able to implement both server and client side scripting and pull the current user’s email address, you can use this guide to preauthorize a Yammer session so apps utilizing the JS SDK will be as seamless as possible.

Prerequisites and Assumptions

You have created an app in Yammer and properly configured the JavaScript Origins
You have an app utilizing the Yammer JS SDK with users manually authenticating as per our documentation at https://developer.yammer.com/docs/js-sdk
You can utilize both client and server side scripting. The language and method of implementing the server-side scripting component is entirely dependent on your specific environment and configuration.
You can obtain the current user’s email address from the server’s side

Procedures

Obtain a Verified Admin token for your application in one of the following 2 ways
1. Create the app with a Verified Admin account and then in the app’s Basic Info page, click “Generate a developer token for this application.” Note that you’ll need to use this app’s info in the JS SDK and any subsequent calls.
2. Use the process outlined at https://developer.yammer.com/docs/test-token with a Verified Admin account to get an OAuth token for that VA account. Note that you must use the app info used to generate this token in all future steps.
Obtain the current user’s email address in the server-side script.
Using the VA token obtained in step 1 to authenticate, pass the user’s email address to our Get User by Email Address endpoint documented at https://developer.yammer.com/docs/usersby_emailjsonemailuserdomaincom, and then process the response
1. If the call to the API endpoint returns a 200 OK response, first check the “state” field to make sure the user is “active” and if so, store the “id” field that’s returned and go to step 4
2. If the call returns a 404 or a state other than “active,” direct the user to finish creating and activating their account however you like.
Once you have the user’s ID, you can pass it to our Impersonation endpoint to obtain a pre-authorized OAuth token for that user. This endpoint is documented at https://developer.yammer.com/docs/impersonation and must use the VA token obtained in step 1 to authorize the call, and the consumer_key of your JS SDK app.
You now have an OAuth token for the current user. When generating the code being passed to the browser, have the client side JS SDK code first call yam.platform.getLoginStatus and if there’s no active session and you have a token from step 4, pass that token to yam.platform.setAuthToken($tokenFromStep4, optional_callback_function_if_desired(response)). If you don’t have a valid token, direct the user to finish setting up their Yammer account.
Continue making JS SDK calls as you normally would, without needing the user to authenticate.

Pseudocode

Note: This code should live on the page where you’re hosting the Yammer JS SDK app. This code should be rewritten in your server side scripting language and curl library’s format. This code should go right before your JS SDK Code.

<% // Start server side code
/* You’ll first need to get a Verified Admin OAuth token for your app.  I’m storing it in $theToken here */

/*
You will also need a way to obtain the email address of the current user.  This will be different depending
on where you’re hosting the Yammer app, but the most common way is to query the environment hosting the app
to get the logged on user’s email address.  I’m storing it in $theUserEmail here
*/

 

$theToken = “123-AoieuarKhwarIalIHY39A”;        // Store VA Token

$theUserEmail = getAuthenticatedUserEmail();    // Store user’s email

 

/* Get User ID */

$curl = newCurlObject();                        // This will be specific to your language and curl implementation

$curl.setHeader(“Authorization: Bearer “ + $theToken); // Sets the auth header

$theEndpoint = “https://www.yammer.com/api/v1/users/by_email.json?email=” + $theUserEmail;

$response = $curl.execute($theEndpoint);        // Make a call to the API endpoint with the email address appended

$theCode = $curl.getStatusCode();               // Get the response code from the API call

if($theCode == 404)

  $goodUser = false;                              // This user can’t be impersonated

 

$theUserData = json_decode($response);          // Get the json data into an array

if($theUserData["state"] == "active") {

  $goodUser = true;                               // This is an active user

  $theUserID = $theUserData["id"];                // Store the user’s ID

} else {

  $goodUser = false;                              // This user isn’t active and can’t be impersonated

}

/* We now know if the user is an active Yammer user and if so, their User ID */


/* Get impersonated OAuth token for the user */

$clientId = "your_client_id";                   // Obtained from the Basic Info section of your app under Client ID

$curl = newCurlObject();                        // This will be specific to your language and curl implementation

$curl.setHeader("Authorization: Bearer " + $theToken);   // Sets the auth header

$theEndpoint = "https://www.yammer.com/api/v1/oauth/tokens.json?user_id=" + $theUserID + "&consumer_key=" + $clientId;

$response = $curl.execute($theEndpoint);        // Make a call to the Impersonation API endpoint with the user id

$theCode = $curl.getStatusCode();               // Get the response code from the API call

if($theCode == 200) {

  $theTokenData = json_decode($response);         // Get the json data into an array

  $theUserToken = $theTokenData["token"];         // Store the impersonated token

}

 

/*
At this point you have the info you need from the server side scripting and you need to inject it
into the code sent to the browser.  Ending server side code
*/
%>