Enhancing Your Office 365 Groups Using Custom Connectors and Cards for Groups

Wictor Wilen

by Wictor Wilen on 11/23/2015

Share this:

Article Details

Date Revised:

Applies to:
Connectors, custom Connectors, groups, Office 365, Office 365 Connector Cards

Wow, November 18 was quite a day for developers in Office 365! Microsoft announced tons of new features at the Microsoft Connect(); 2015 virtual conference. We’ve seen the general availability release of the Microsoft Graph and a bunch of new APIs added to the Microsoft Graph beta end-point and more. One of the features that I really have been waiting for is the Office 365 Connectors for Groups and the Office 365 Connector Cards.

The Office 365 Connectors for Groups allow users of Office 365 Groups to add integrations to their Office 365 Groups. Connectors can be seen as services and events that you subscribe to and then the services, when certain events happen, posts information to the Group activity feed. Microsoft included a set of pre-configured Connectors that anyone can add or you can create your own Connector and customize it for your needs. For instance, there are built-in Connectors for Twitter, Github, RSS feeds and Trello. The possibilities for this are endless!

In this post, I will show you how to create your own Connector and Connector Card. In this sample, we will assume that we have a CRM system that monitors incoming requests, such as RFIs and RFPs, and we want these events to be posted to a Group in Office 365.

Enabling Connectors

The Connector framework is in preview so in order to start working with them, we need to enable this preview. This is done by navigating to a Group in Office 365 and then append &EnableConnectorDevPreview=true to the URL (figure 1).

Append this string to the URL to enable the Connector framework preview: &EnableConnectorDevPreview=true
Figure 1: Append this string to enable the Connector framework preview

Once we have enabled the Connector preview, you will find a new option called Connectors (figure 2) under the "…" menu. Click on that to start configuring your Connectors. In the task pane that is shown, you can see all the different default Connectors that you can add and configure without doing any kind of development.

The Connectors option enabled for an Office 365 Group
Figure 2: The Connectors option enabled for an Office 365 Group

Creating an Incoming Webhook

In our case, we want to do a completely custom Connector (figure 3). We create these by choosing the "Incoming Webhook" Connector and then click Add.

Create a custom Connector for your Office 365 Group by choosing the “Incoming Webhook” Connector
Figure 3: Create a custom Connector for your Office 365 Group by choosing the “Incoming Webhook” Connector

To configure our Incoming Webhook, we need to give it a name and optionally add an image for the Connector. Once that is done, click Create to create the Webhook. When it is created, you will see an input box with a URL in it. This is the Webhook and we need this URL in our custom Connector handler. The URL is unique for this Group and Webhook and we can, of course, remove the Webhook if we want to disable it.

Note that when the Webhook is created, a notification of this will be sent to the Activity feed, the notification contains the Webhook URL.

Posting a message to the Webhook

Once you have the Incoming Webhook URL, you can build your own custom solution that posts messages to the Activity feed within the Office 365 Group. All we need to do is to issue a POST request with JSON payload to this URL. There is no need for authentication—we assume that this URL is unique and no one figures it out :) It’s a GUID, folks!

The JSON payload describes the Connector Card, which can have simple properties such as title, text, images and a color, and more advanced properties such as actions and sections with facts. Figure 4 below shows a Connector card with (1) the Connector info, (2) the Connector card title and text, (3) a section with activity details and (4) facts connected to the section and finally, (5) actions.

Elements of an Office 365 Group Connector card
Figure 4: A Connector card illustrated

This Connector card can be added to the Office 365 using any kind of tool that can send a post request. Let’s see how it can look like when doing it using Node.js. You can find a more exhaustive example at https://github.com/wictorwilen/Office365_Connector_Demo.

var request = require('request')

  method: 'POST',
  uri: 'https://outlook.office365.com/webhook/.....',
    'content-type': 'application/json',
  body: JSON.stringify({
    'title': 'New RFI added to CRM',
    'text': 'A new RFI from [Contoso](http://www.contoso.com) has arrived',
      "@context": "http://schema.org",
      "@type": "ViewAction",
      "name": "Lookup Contoso in CRM",
      "target": ["http://crm.fabrikam.com/customer/Contoso"]
}, function(error, response, body){

We create a new HTTP POST request and as URL, we use the Webhook URL that we generated previously. Then we need to make sure that we use application/json as the content type for the request. The body of the request is a JSON formatted payload. In the example above, we provide a title and a text (note the Markdown formatting) as well as an action. The JSON payload is thoroughly described in the Outlook Dev Center, so there is no need to delve into that too much. When the request is sent, it will return a status code of 200 if successful. If not successful, you will see response code 400 if you have used the wrong format, 404 if you specify the wrong Webhook URL and you can even get throttled (429) if you send too many requests.


That was so easy! With just a few lines of code and a simple configuration, we can make the Office 365 Groups experience into something integrated into your organization or your customer’s organization. Imagine the possibilities with this.

I’m really impressed with how Microsoft builds their products and services now, how they adhere to modern development techniques, how they innovate, and how they make my job so much more fun! I’ve said it before—Groups are here to stay and they do it big time!


You can read Wictor’s original blog here: http://www.wictorwilen.se/enhancing-your-office-365-groups-using-custom-connectors-and-cards-for-groups

Topic: Development

Sign in with

Or register

  • Not working on our tenancy. Enabling the connector interface does give the extra menu but selecting the connectors menu gives a blank popup with just a close link on it.
  • Excellent article, thanks Wictor! It works like a charm. A really cool feature, that makes Office Group really valuable.