Yammer Platform

Welcome. We are excited that you are interested in the Yammer Platform. Our platform consists of a set of open APIs and tools that enable you to bring Yammer’s social services to your application.

Build your first Yammer App

Before you begin, leverage the knowledge of thousands of Yammer platform experts by joining the YDN at https://www.yammer.com/yammerdevelopersnetwork.

Introduction

This is a step-by-step guide to building an application on the Yammer Platform. To walk you through the process, we’ll give you some examples from a simple scheduling app integrated with Yammer called Sched.do (www.sched.do). The code for the application is at https://github.com/yammer/sched.do.

Step 1: Register an app with Yammer

Step 2: Implement Authentication

Step 3: Write data into Yammer using Open Graph

Step 4: Display data from Yammer using Embed

Next Steps: App Directory Readiness and Submission

Prerequisites

To get started, you’ll need a Yammer network to build and test your app. You can sign up for free at www.yammer.com.

Step 1: Register an App with Yammer

Go to https://www.yammer.com/client_applications. Click on the “Register new App” button. Please note that the app will be linked to the same Yammer network you used to create it. This is the network you’ll use to access, edit and test your app.

SampleBasicConfig-1024x791

Once you enter the initial information, you’ll be asked to complete basic configuration. The required fields are:

1. Application Name: The app name which will appear in Yammer’s activity stream.

2. Organization: The name of the organization affiliated with your app.

3. Website: Your organization’s website.

4. Support e-mail: An email address which users of your app can contact for support.

5. Expected Redirect/Redirect URI: Where Yammer will redirect to after the authentication flow is complete.

- For static urls, use the full url, without the leading `www`. For example, https://user.dynamics.com

- For dynamic url subdomains such as https://<instancename>.dynamics.com, use only the domain name i.e. https://dynamics.com

Save changes to finish registering your app.

Step 2: Implement Authentication

The next step is to implement an authentication mechanism for your app to connect to Yammer. The authentication is an OAuth 2 flow beginning with the user authenticating with their Yammer credentials. Next, the user authorizes your app to connect to their Yammer network. The end result is a token your app will use to write events to Yammer and retrieve Yammer data. Here is a step-by-step tutorial of how the Yammer server-side OAuth 2 flow works:

A. User Authentication

Typically, a “Sign in with Yammer” button on your app’s login page will initiate user authentication. When the user clicks the button, redirect them to Yammer’s OAuth dialog at:

https://www.yammer.com/dialog/oauth?client_id=[:client_id]&redirect_uri=[:redirect_uri]

`client_id` is in your app details above. For dynamic URIs, the domain of the `redirect_uri` should match the Redirect URI entered in the app registration page. For static URIs, the full `redirect_uri` should match.

“Sign in with Yammer” from Sched.do app home page

SchedoLargeLogin-1024x539

Oauth dialog launched on clicking “Sign in with Yammer”

Oauth2Login-1024x649

B. App Authorization

Once Yammer has successfully authenticated the user, the OAuth dialog will prompt them to authorize the app. If the user clicks “Allow”, your app will be authorized. The OAuth Dialog will redirect the user’s browser via HTTP 302 to the redirect_uri with an authorization code: http://[:redirect_uri]?code=[:code]

Oauth2AppAuthorization-1024x618

C. App Authentication

Next, submit a GET on the OAuth Token Endpoint, passing in the authorization code you got above and your app secret. The endpoint is:

https://www.yammer.com/oauth2/access_token.json?client_id=[:client_id]&client_secret=[:client_secret]&code=[:code]

Yammer will return an access token object as part of the response, which includes user profile information. From this object, parse out and store the “token” property. This token is long lived (years) and will be used to make subsequent API calls to Yammer.

Sample Code

Here is sample code, using Rails, to help you get started on authentication. We’ll use OmniAuth, a library that makes it easy to implement authentication to Yammer (https://github.com/intridea/omniauth), and the OmniAuth Yammer gem containing the Yammer strategy for OmniAuth 1.0 (https://github.com/le0pard/omniauth-yammer).

1) Add the following to your Gemfile:
   gem 'omniauth', '~> 1.0'
   gem 'omniauth-yammer'
2) Run
   bundle install
3) Add the OmniAuth middleware to your Rails app by updating config/initializers/omniauth.rb to include:
   Rails.application.config.middleware.use OmniAuth::Builder do
   provider :yammer, 'Client Id', 'Client Secret'
   end
4) Make sure you set the URL in the “Redirect URI” field of your app settings to:

http://yourappurl/auth/yammer/callback
5) Setup your application to handle the callback URL. Typically you would retrieve the OAuth access token and create   a new user session

   - Create a new sessions controller with the create action:
     rails generate controller sessions create

   - Add the following to your routes.rb file:
     match '/auth/yammer/callback', :to => 'sessions#create'

   - In your sessions_controller.rb file define the create method:
     def create
     auth = request.env['omniauth.auth']
     render :text => auth[:credentials][:token]
     end

Step 3: Write Data into Yammer Using Open Graph

Once your app has been successfully authenticated, it can write data into Yammer or read data from Yammer. Most commonly, your app will post a user’s activity to Yammer as Open Graph objects. For example, let’s say a sales rep updated an opportunity’s value to a large amount.

User activity displayed in Yammer’s Activity Stream

ActivityStream-1024x575

Here is a step-by-step tutorial of how to write a business activity to Yammer:

A. Define the Activity

Structure your business activity in the following format:

<Actor> <Action> <Object> on <App Name>: <Message>
For example, “Sidd Singh created ‘Lunch Meeting’ on Sched.do: ‘Hey, let’s get sushi!’”

<Actor> is the Yammer user who created the activity. The actor is linked to the user’s Yammer profile when the activity is displayed in Yammer.
<Action> is a verb that describes the activity. Currently supported verbs are: create, update, delete, follow, like.
<Object> is the Open Graph (OG) object on which action was taken. An OG object represents an entity instance in your application, like a particular Event (Lunch Meeting) in Sched.do. OG objects are uniquely identified with their URL and their title is displayed in Yammer as a link to the URL. We recommend sending Yammer as many properties for your OG objects as you can for appropriate display.
<App Name> is the name of your app (specified when registering your app).
<Message> is a free text field to provide context to the activity.
<Users> is an optional field which allows you to specify recipients of the activity. By default the actor and their followers on Yammer receive the activity. See more details at http://developer.yammer.com/opengraph, “Delivering to Users”.

B. Write the Activity

Once you have defined what your activity should look like, the next step is to POST this activity into Yammer’s activity stream. This is done by defining the appropriate JSON payload and posting it to the API endpoint below using the Oauth access token you obtained earlier.

POST to:

https://www.yammer.com/api/v1/activity.json

Make sure to set the Content-type of the request body to “application/json”.

Oauth access token sent as a “Bearer” token in the “Authorization” request header:

GET /api/v1/messages/following.json HTTP/1.1 
Host: www.yammer.com 
Authorization: Bearer abcDefGhi

For more details on the “Bearer” token refer to http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-23

JSON Payload for the activity:

{
"activity":{
"actor":{"name":"Sidd Singh",
"email":"sidd@xyz.com"},
"action":"create",
"object": {
"url":"https://www.sched.do",
"title":"Lunch Meeting"
},
"message":"Hey, let’s get sushi!",
"users":[
{"name":"Adarsh Pandit",
"email":"adarsh@xyz.com"}
]
}
}

Code excerpts for activity creation from Sched.do code on github: https://github.com/yammer/sched.do/blob/master/app/jobs/activity_creator_job.rb#L33-L51

def post_yammer_activity
user.yammer_client.post('/activity', json_payload)
end
def json_payload
{
activity: {
actor: {
name: user.name,
email: user.email
},
action: action,
object: {
url: event_url(event),
title: event.name,
image: 'http://' + ENV['HOSTNAME'] + '/logo.png'
}
},
message: '',
users: invitees_for_json
}
end
def event
@event ||= Event.find(event_id)
end
def invitees_for_json
event.invitees.map { |i| { name: i.name, email: i.email } }
end

Step 4: Display Data From Yammer Using Embed

To display data from Yammer in your HTML based application, Yammer provides embeddable JavaScript widgets that display a snapshot of a specified feed and function as a scaled-down version of Yammer. Using embed, you can display My Feed, a Group Feed, a Topic Feed, a User Feed or an OG object feed.

To display My Feed, add the following embed code to your HTML page

<!DOCTYPE HTML>
<html>
<head></head>
<body>
<script data-app-id="Client Id"
src="https://assets.yammer.com/platform/yam.js"></script>
<script> yam.connect.embedFeed({
 container: "#embedded-feed",
 network: "fourleaf.com" // network permalink (see below)
 });
</script>
<div id="embedded-feed"></div>
</body>
</html>

To retrieve the feed ID and network permalink, please navigate to the feed in the Yammer web application and copy it from the URL:

embed-feed

For more details on embedding the different types of feeds, especially the OG object feed, please look at http://developer.yammer.com/connect, “Embed feeds”.

Next Steps: App Directory Readiness and Submission

Once your app is built and tested, make it ready for inclusion in Yammer’s App Directory by enabling the “Try It” functionality. Next, go to your app configuration page in Yammer, complete the App Directory Config section and deploy the app to your network.

Finally, submit your app to Yammer for App Directory approval by Deploying to Global App Directory.