Open Graph

Once you have authenticated a Yammer user, you should write their activity in your app to Yammer. This activity will be displayed in engaging ways to the user’s Yammer network. People in the network will click through the activity into your app, helping grow it’s usage. Examples of activity are: In a CRM app, a sales rep updated an opportunity’s probability of closing to a lower number. In a scheduling app, an employee created a lunch meeting. Open Graph (OG), a light weight data integration protocol, is used to define the activity which is posted to Yammer as an OG object.

Format

The activity takes the format:

<Actor> <Action> <Object> on <App Name>: <Message>

Using our two examples earlier, the activities would look like 1) “Sidd Singh” updated “Contoso Ltd Deal” on Dynamics CRM: Changed Probability from 90% to 60% 2) “Sidd Singh” created “Lunch Meeting” on Sched.do: Hey, let’s get sushi!

User activity displayed in Yammer’s Activity Stream

ActivityStream-1024x575

Next, let’s take a look at the various pieces of an activity:

Actor

When writing an activity into a Yammer network, an actor must be specified. The actor is a Yammer user that performed an action in your app. If the actor exists in the Yammer network, the story will be delivered to the actor and others depending on the delivery rules specified (please see below). If the actor doesn’t exist, the story will not be delivered. The actor is linked to the user’s Yammer profile when the story is displayed in Yammer.

Action

Similarly an action must be specified. The action is a verb that describes what happened to the object e.g. created, updated, deleted, followed, liked, etc).

Object

The key piece of any activity 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) or a CRM Record (Contoso Ltd. Renewal Deal). 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.

When your app sends an activity to a Yammer network, a corresponding OG object is created in the Yammer if it doesn’t already exist. When an OG object exists (with the same URL), it is updated appropriately.

Delivery

Once you have formatted your activity, the next step is to deliver this activity to the user’s Yammer network. 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 during authentication.

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 “Sidd Singh” created “Lunch Meeting” on Sched.do: Hey, let’s get sushi! :

{
"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"}
]
}
}

This activity will appear in the Yammer Activity Stream Ticker (shown above) and will be delivered to the actor, the actor’s followers and the people specified in the “users” list, in this case to Sidd Singh, his followers and to Adarsh Pandit. The OG object of this activity “Lunch Meeting” will be searchable by any user in the actor’s Yammer network.

Delivery Rules

The “private” parameter can be used to restrict the recipient list for the activity. By default this parameter is false but if set to true, the activity will only be delivered to the users included in the activity’s “users” list, as well as the actor. If “private” is set to false (or not included), the activity will be delivered to the users included in the activity’s “users” list, the actor in the story and the actor’s followers. For maximum visibility of your app activities, we recommend going with the default public model where the “private” parameter is not included.

The OG object of a public activity is searchable (and autocompletes in real time search) in Yammer by any user in the actor’s network. For a private activity, only the actor and the “users” list can view the associated OG object.

Schema

Below is a detailed description of the activity schema and delivery.

Activity Envelope

An activity envelope encapsulates the activity (actor, action and object) as well as an optional delivery list for the activity. It is a JSON object with the following fields:

actor (required) – a user object representing the Yammer user performing the activity.

action (required) – the name of the action being performed.

object (required) – an Open Graph (OG) object representing the object being acted upon by the actor.

private (optional) – Boolean. Only show this activity and object to the targeted users. Defaults to false.

user message (optional) – 200 character text message describing this activity. Defaults to blank.

users (optional) – an array of user objects to deliver the activity to.

User

Every activity must specify a user as the actor. Activities can also include a set of user objects for delivery of the story. Users are defined by including:

email (required) – user’s email address.

name (optional) – user’s full name.

Object

Every activity must specify exactly one OG object that has been acted upon. OG objects are uniquely identified by their URL in your app. In addition to including the URL of the object, the activity can contain attributes that more fully describe the object. We recommend setting as many of these attributes as you can for appropriate display in Yammer.

url (required) - location of the Open Graph Object. This only works for publicly accessible content.

type (optional) - reference to associated Open Graph Object type.

title (required) – title of the object as it should appear in stories.

image (optional) – thumbnail image that represents the object.

description (optional) - A one to two sentence description of the object.

Supported Object Types

By default the following object types are supported(see below). You can define custom object types by following the instructions in the “Custom Objects and Actions” section below.

page (default)

place

person

department

team

project

folder

file

document

image

audio

video

company

Supported Actions

By default the following actions are supported(see below). You can define custom object types by following the instructions in the “Custom Objects and Actions” section below.

create

update

delete

follow

like

Delivering Activity

HTTP Method: POST
URL: https://www.yammer.com/api/v1/activity.json
Authentication: OAuth 2 Access Token
Request Content-Type: application/json
Request Content Schema: { ActivityEnvelope } || [ { ActivityEnvelope } (, { ActivityEnvelope })* ]
Expected Response Code: 202 (Accepted)
Expected Response Body: None

Embed.ly

When you send an OG object to Yammer, it checks to see if it can scrape more OG metadata from the page at the OG object’s URL. Yammer uses a service called Embed.ly to visit the page and, if the page is public, retrieve any OG metadata present on the page. If Embed.ly finds OG metadata that Yammer didn’t receive from the activity related to the object, then Yammer saves the new metadata. OG metadata that Yammer receives via an activity is always preferred over OG metadata that Yammer receives from Embed.ly. If Embed.ly can’t reach the page at an object’s URL (because it’s behind a firewall or requires authentication), then Yammer leaves the object as is with the metadata specified in the activity story.

In general, adding OG metadata to pages in your web application will make objects render more richly in applications that support Open Graph (like Yammer and Facebook). Below is an example of how to embed the Open Graph metadata that Yammer can use in a web page’s header.

〈head〉
...
〈meta property="og:type" content="file"〉
〈meta property="og:title" content="Yammer ROI.pdf"〉
〈meta property="og:image" content="/images/Yammer ROI.png"〉
〈meta property="og:description" content="A set of charts showing the ROI of deploying Yammer over time."〉
...
〈/head〉

See http://ogp.me/ for more details.

Custom Object Types & Actions

Your app can specify custom object types and custom actions to create richer activities. The currently supported standard object types and actions are available to all apps, however custom object types and custom actions are scoped to your app.

Standard action:

Screen-Shot-2013-04-05-at-4.35.01-PM

Custom action:

Screen-Shot-2013-04-05-at-5.29.49-PM

Custom object types and actions can be created in the “Open Graph” section of your app. Find this section by navigating to your client applications page ( https://www.yammer.com/client_applications ), selecting your app and then selecting the “Open Graph” section in the left hand navigation menu.

App settings page for specifying custom object types and actions for your app

Screen-Shot-2013-04-05-at-5-1.23.57-PM

Enter a namespace for the app and enter custom object types and actions based on the form. Yammer will automatically determine when to use the present or past tense of the custom actions, and when to use the singular or plural form of the object types.

In order to use custom item types in the activity, use the following format of “namespace:customItem”.

Single Activity with custom object types and actions

{
  "activity": {
    "actor": {"name": "Norman O'Shea", "email": "norman@yammer.com"},
    "action": "github_test:commit",
    "object": {
      "url": "https://github/yammer-test/yam-git-OG",
      "type":"github_test:repository",
      "image":"https://a248.e.akamai.net/assets.github.com/images/modules/dashboard/octofication.png",
      "description":"yam-git-OG -repository to test build in Yammer integration for Github",
      "title":"yam-git-OG"
    },
  "private": "false",
  "message": "testing commit"
  }
}

 

Sample Activities

Single Activity Story (non-public)

In this context, “non-public” means the provided URL, “https://dox.com/file/abc123″, cannot be publicly accessed and scraped for OG metadata by Embed.ly. Therefore all OG metadata must be passed in the object section of the activity JSON.

{
  "activity": {
    "actor": {"name": "Jim Patterson", "email": "jpatterson@alpinestyle.com"},
    "action": "create",
    "object": {
      "url": "https://dox.com/file/abc123.pdf",
      "description": "A set of charts showing the ROI of deploying Yammer over time.",
      "video": {
      "width": 500,
      "height": 400
    },
    "type": "file",
    "title": "Yammer ROI.pdf",
    "image": "https://dox.com/file/abc123.png"
  },
  "private": "false",
  "message": "This is the updated version for the conference.",
  "users": [
    {"name": "Mary Shamone", "email" : "mshamone@alpinestyle.com"},
    {"name": "Christina Ammerlaan", "email" : "cammerlaan@alpinestyle.com"}
  ]
  }
}

Example: Single activity (public object)

In this context, “public” means that all necessary OG metadata can be publicly accessed and scraped from the provided URL. When an activity’s target object has OG metadata that is publicly accessible, it is unnecessary to send any optional object metadata in the activity JSON.

{
  "activity": {
    "actor": {"name": "Jim Patterson", "email": "jpatterson@alpinestyle.com"},
    "action": "create",
    "object": {
    "url": "https://dox.com/file/abc123.pdf"
  },
  "private": "false",
  "message": "This is the updated version for the conference.",
  "users": [
    {"email": "mshamone@alpinestyle.com", "name": "Mary Shamone"},
    {"email": "cammerlaan@alpinestyle.com", "name": "Christina Ammerlaan"}
  ]
  }
}

Example: Multiple activity stories

A third party application can send over multiple activities in one batch. Sending over multiple activities can help prevent an application from hitting the rate limits of the Yammer API.

{
"activity": [
{
  "actor": {
    "name": "Jim Patterson",
    "email": "jpatterson@alpinestyle.com"
  },
  "action": "create",
  "object": {
    "type": "file",
    "image": "https://dox.com/file/abc123.jpg",
    "title": "Yammer ROI.pdf",
    "url": "https://dox.com/file/abc123.pdf",
    "description": "A set of charts showing the ROI of deploying Yammer over time.",
    "video": {
      "width": 500,
      "height": 400
    }
  },
  "private": "false",
  "message": "This is the updated version for the conference.",
  "users": [
    {"email": "mshamone@alpinestyle.com", "name": "Mary Shamone"},
    {"email": "cammerlaan@alpinestyle.com", "name": "Christina Ammerlaan"}
  ]
  },
{
  "actor": {
    "name": "Jim Patterson",
    "email": "jpatterson@alpinestyle.com"
  },
  "action": "update",
  "object": {
    "type": "file",
    "image": "https://dox.com/file/def456.jpg",
    "title": "Yammer Rollout Strategy.pdf",
    "url": "https://dox.com/file/abc123.pdf",
    "description": "A customer-facing document with best practices on how to roll out a Yammer network",
    "video": {
      "width": 500,
      "height": 400
    }
  },
  "private": "false",
  "message": "I updated the table of contents to include the appendix.",
  "users": [
    {"email": "mshamone@alpinestyle.com", "name": "Mary Shamone"},
    {"email": "cammerlaan@alpinestyle.com", "name": "Christina Ammerlaan"}
  ]
  }
  ]
}