Getting Started

Welcome! Our platform consists of a set of open APIs and tools that enable you to leverage Yammer’s social services for your application.

This step-by-step guide will help you build an application on the Yammer Platform. In order to walk you through the process, we will give you examples from a simple scheduling app called Sched.do (www.sched.do). This app is closely integrated with Yammer, using all of the documented capabilities the API has to offer. The code for Sched.do is located here: https://github.com/yammer/sched.do.

.

Build your first Yammer App

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 will need a Yammer network to build and test your app.

Sign up for free at: www.yammer.com

Join StackOverflow

Before you get started, we welcome you to join StackOverflow and use the #yammer tag.

New to StackOverflow?   See how it works here: http://stackoverflow.com/tour

Ready to ask your questions?   http://stackoverflow.com/tags/yammer/

 

 

Step 1: Register an App with Yammer

Go to https://www.yammer.com/client_applications. Click on the “Register new App” button. Please note, when you create an app, this app will be linked to that related Yammer network. This is the network you will use to access, edit, and test your application.

Reg app

Register a New App. 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. Support e-mail: An email address, which users of your app can contact for support.

4. Website: Your organization’s website.

5. Agree to Terms of Service and Continue

Reg Screenshot

Once you have registered your app fill out the Basic Info

Basic Info

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

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. The user then 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. This is the three-part server-side OAuth 2 process and tutorial:

A. User Authentication

A “Sign in with Yammer” button on your app’s login page will initiate user authentication. When the user clicks the button it redirects 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”

Login

B. App Authorization

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

 

 

OAuth2

C. App Authentication

Submit a GET request on the OAuth Token Endpoint, passing in the authorization code you received above, plus 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 will be used to make subsequent API calls to Yammer and will not expire.

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 users activity to Yammer as Open Graph objects. For example, let’s say a sales rep updated the price of a sales deal.

User activity displayed in Yammer’s Activity Stream

activity stream

 

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. These are the verbs we currently support:

· Create, Update, Delete, Follow, and Like      *In addition, you can create custom verbs.

<Object> is the Open Graph (OG) object on which the action was taken. An OG object represents an entity instance in your application, for example, an event (e.g. lunch meeting) in Sched.do. OG objects are uniquely identified with their URL. 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 specified feed. These widgets function as a scaled-down version of Yammer. Using Yammer 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 Embed Group ID and network permalink, navigate to the feed in the Yammer web app and copy it from the URL:

Embed

For more details on embedding 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 to be included in Yammer’s App Directory by enabling the “Try It” functionality: http://developer.yammer.com/enabling-try-it/. Prior to launch, please make sure you have prepared your website, landing page, and marketing material.

Next, go to your app configuration page in Yammer, complete the App Directory Config section and deploy the app to your network: https://www.yammer.com/client_applications

Finally, submit your app to Yammer for App Directory approval by Deploying to Global App Directory. A member of the Yammer Platform team will reach out with next steps.