Integrating your SaaS app with Yammer

So, you have an enterprise SaaS app and Yammer would be the perfect place to integrate. Follow this guide to integrate your app with Yammer and connect to over 10 million verified enterprise cloud users in more than 300,000 companies.

Before you start implementing your Yammer integration, there are a few things to consider in terms of architecture:

• In Yammer, each OAuth2 access token is specific to a user/network pair (and also rate limited that way).
• When a user authenticates with Yammer, they'll receive a token for their root network. If a user is only a member of an external non-root network, they will not be able to authenticate with your app.
• Yammer verifies the email addresses of all their users before they access the app, so you can always be sure of that.
• Yammer doesn't seem to have a concept of refresh tokens, so if a token expires or is no longer valid for whatever reason, you'll need to have the user re-authenticate with Yammer.

Before you can start integrating with Yammer, you'll need to get yourself a Yammer network. To do that, go to https://www.yammer.com/ and sign up your SaaS company.

Keep in mind that you'll need to use your company e-mail to sign up. This is fine, as you need a Yammer account in order to create your Yammer app.

Follow these instructions on the Yammer site to create an app.

Some tips:

• Yammer only lets you supply 1 redirect URI per app, meaning that if you have 3 different environments (e.g. development, test and production) you should create 3 apps, and only have one of them global (the production one).
• The redirect URI does not have to match perfectly - it only has the match the beginning of the URL you are redirecting to. For example, if you redirect to https://example.com/login then your redirect URI can be https://example.com.
• Yammer also allows sub-domains in redirect URIs.
• Be sure your production redirect URI is HTTPS, otherwise the Yammer OAuth dialog will point out that the app transmits data insecurely.

Once you've created your Yammer app, it's time to start thinking about how you're going to integrate.

In Yammer, the main integration point is activities. An activity in Yammer will show up in the activity feed on the sidebar and will update users on what's going on in your SaaS app.

Keep in mind that, although activities are a straightforward way to integrate your app into Yammer, they're not the only way to integrate your app. Yammer has a full-featured REST API that includes a sophisticated messaging system that can be used to great effect (more on that later).

It's important to understand that activities in Yammer revolve around Open Graph (OG) objects. An OG object is used to represent your app's objects inside Yammer. The URL of the OG object acts as its identifier, and you can also use that OG object URL to update your objects in Yammer.

Furthermore, you can post messages to OG objects, which can be a useful integration point for SaaS apps.

In Process.st, we decided that we wanted to represent to push checklists created in Yammer-linked accounts to Yammer. Each time a checklist was started or updated, we wanted that information to appear in the activity feed.

An OG object in Yammer typically has the following fields:

• url: the permanent link to your app's object
• type: the type of the object (defaults to "page"), can be a custom a type
• title: self-explanatory (also shows in the activity feed)
• description: self-explanatory (shows in the activity feed on mouseover)
• image: the URL to a thumbnail of the object (shows in the activity feed on mouseover)

Only the url field is required, and most of the other information can be pulled by Yammer if the URL is publicly accessible.

The URL

All checklists in Process.st have a permanent link with the following format:

https://app.process.st/checklists/{{ checklist_id }}

Since it's permanent, it's suitable for the OG object URL. 

Title and description

Since all checklists have names, choosing the title was straightforward.

The description, however, was a bit tricker. Should it be the checklist's template's description? Should it be the template name?

Ultimately, we went with the template name, as every checklist is guaranteed to have one set, and it gives much more valuable contextual information.

Choosing a type

Next up, we needed to choose a type. These are the built-in types from the Yammer documentation:

• page (default)

• place

• person

• department

• team

• project

• folder

• file

• document

• image

• audio

• video

• company

From my experience, the type doesn't have a huge effect on how Yammer renders your activity, other than the noun used to describe it. Since none of the built-in types were closed enough to a "checklist", we decided to create our own OG type called ps:checklist. It also seems that when you create a new OG object type, all apps (including your development and test apps) can make use of them, so they only need to be defined once, ideally in your production app.

What's a suitable thumbnail?

Since there wasn't a natural image for our checklists, so we decided to leave this blank (and have it default to the Process.st logo). However, if our checklists had a cover page, that could've been a good candidate. Another option could've been a generic checklist image.

If you leave the image field blank, it'll show your app icon.

Putting it all together

Imagine in Process.st we started a new checklist named "John Smith" using the template "Employee Onboarding". This is an example of the OG object for that checklist in JSON:

{
    "url": "https://app.process.st/checklists/uanul6FqWCzqVhRp8aNDiw",
    "type": "ps:checklist",
    "title": "Process.st Yammer Integration",
    "description": "Template: Integrating your SaaS app with Yammer"    
}

The Yammer documentation heavily pushes the use of activities in Yammer apps. That makes sense, as almost any app has some activity that they can push.

However, if your app has comments or attachments, and these are attached to some sort of object, they're a perfect candidates for integration with the Yammer message system.

The advantages of using Yammer messages over activities (where appropriate) include:

1. Messages appear in the main Yammer window, as opposed to the smaller activity feed.
2. If messages are posted to OG objects, then they are grouped there, making them more useful to your Yammer-linked customers.
3. Attachments in messages will appear in the Files area of Yammer. Activity OG objects, even those with type "file", will not.

If you do decide to use messages in your integration, keep in mind that by default messages will be posted to "All Company" if no group or user is specified. This is not a good default in most cases, and it is recommended that you add a mechanism that allows users to specify a group to post to. 

It is also recommended that when integrating with the Yammer message system that you let the user know somewhere that they will be posting to Yammer as well.

In Process.st, users can post comments to checklists. Since comments are attached to checklists, it seemed to be a natural fit that we model comments as messages in Yammer.

A message in Yammer has the following format:

• body: The message body.
• group_id: If not set, the message will be posted to "All Company".
• replied_to_id: The message id if this message is a reply. This would useful if Process.st supported nested comments.
• direct_to_id: The user id if this is a private message. For comments, this could be used if the a Yammer user was @mentioned in Process.st.
• broadcast: If set to true, it will sent as a message to all users in a group. We didn't use this as it seemed like it would be pretty spammy.
• topic0...topic20: Topics are like message tags in Yammer. Could potentially be used to mark all messages sent from Process.st as such. We didn't use it.
• attachment0...attachmentN: This is useful for pushing attachments to Yammer as messages. We didn't use this for comments, but we used it when integrating our attachments feature.

In addition to the message fields, there are several OG object fields. This is how you associate a message with an OG object.

• og_fetch: If set to false, Yammer won't attempt to download the URL and extract metadata.
• og_url: This most important part. If you're trying to post a message to an existing object, make sure the URL is the same.
• og_image: The thumbnail. Since we were always attaching to objects that already existed, we didn't both with the rest of these fields.
• og_description
• og_object_type
• og_site_name
• og_meta
• og_private

Consider our example of the onboarding John Smith from before. In that case, the URL for the checklist was: 

https://app.process.st/checklists/l1lNS--_hTQle6DEkBtM-A

Now, imagine during the checklist, Cameron posts a comment:

The resulting Yammer form data would be:

​body="I think we should use messages to model Process.st comments in Yammer"
og_fetch="false"
og_url="https://app.process.st/checklists/uanul6FqWCzqVhRp8aNDiw"

And that's it! The message will be attached to the checklist I previously sent to Yammer and to the group "All Company".

Once you've chosen all the integration points for pushing to Yammer, you need to determine what sort of information you can pull from Yammer to give your users a better experience.

In fact, by integrating with Yammer, you are automatically pulling information already: single sign-on (SSO). This is already super handy for Yammer users as that way they don't need to manage two accounts and two passwords.

Beyond that, the most likely integration point for the majority of apps will be autocompletion. The Yammer autocomplete endpoint allows you to ask Yammer for users, groups, topics, etc. that have a given prefix.

Some examples of autocompletion integrations are:

• Autocompleting user email addresses for invitations
• Setting a group for a message that will be sent to Yammer
• Autocompleting files to embed or attach

In Process.st, we integrated with Yammer by using their user autocomplete in our invitation flow.

The autocomplete endpoint in Yammer is pretty straightforward. It has the following parameters:

• prefix: returns all results that have fields starting with the given value. It will still return results even if blank (useful for show results on focus, before the user has typed anything).
• models: a comma-separated list of "modelName:count" pairs. The "modelName" portion is user, group, file, etc. while the "count" portion limits the result set to at most that many results.

In our particular situation, we simplify sent the the particular email address. So if the user were looking for "[email protected]" and started typing "vic", our query string would look like this:

?prefix=vic&models=user:10

Also, as recommended by the endpoint documentation, we wait for the user to stop typing for at least 500 ms before sending our request and we cache it for 5 minutes. This helps to prevent us from hitting the rate limit.

Now that we've gone over how to design your Yammer integration, here's a checklist to use to make sure you've covered everything (based on this checklist in Yammer's documentation)

Use Yammer as your authentication and identity mechanism. Be sure to have a "Login with Yammer" button on your app's login page.

Once you have authenticated a Yammer user, make sure to push their activity from your app in Yammer’s activity feed.

During your app's invitation process, you should use Yammer’s REST API to identify additional members that can be invited to use your app.

Typically this means using the autocomplete endpoint.

Test your app to make sure it works as expected.

Especially pay attention to the case where multiple Yammer users need to be in the same team in your app.

Add buttons to your website that give the option to login with Yammer.

Yammer requires that all apps have a dedicated Yammer landing page that outlines the benefits of using your app with Yammer.

For example, here is the Process.st + Yammer landing page.

Complete the App Directory Configuration section for your Yammer app.

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.