Add Ins Connectors REST APIs Actionable Messages Feedback Blog Code Samples Videos

Office 365 Connectors API Reference

Creating messages through Office 365 Connectors

Connectors use webhooks to create Connector Card messages within an Office 365 group. Developers can create these cards by sending an HTTP request with a simple JSON payload to an Office 365 group webhook address. A developer can generate a group webhook from the "Incoming Webhooks" page in the Connectors catalog, or through the Connector to Office 365 button.

Note: Office 365 Connectors cards are also supported by Microsoft Teams. Developers can create these cards by sending an HTTP request with a simple JSON payload to a Microsoft Team webhook address from the Incoming Webhooks page in the Connectors catalog from Microsoft Teams. For more information, please visit the developer documentation for Microsoft Teams.

Messages

Connector cards can be short text-based messages, or a developer can use sections to display rich or specially-formatted information. When more content is added to the payload, the card scales gracefully.

The simplest message just contains a text variable. The contents of text will be displayed in a card format, along with a sender image and display name. This image and display name are set when the webhook is configured.

{
  "text": "Remember to get milk at the store!"  
}
A text-only message card

Title

A message can also contain a title.

{
  "text": "Remember to get milk at the store!",
  "title": "Today:"
}
A message card with text and a title

To add links to text, developers must include Markdown syntax for hyperlinks.

{
  "text": "Remember to [get milk at the store!](https://wunderlist.com/lists/1101/)",
  "title": "Today:"
}
A message card with a hyperlink

Actions

Actions can be presented to the user by including a Schema.org JSON-LD object in the potentialAction array. We currently support schema.org/ViewAction, which creates a hyperlinked action button at the bottom of the connector card. The text shown on the action button is set by the Action's name parameter, and the destination of the hyperlink is the first link in the target array.

{
  "text": " Remember to [get milk at the store!](https://wunderlist.com/lists/1101/)",
  "title": "Today:",
  "potentialAction": [
    {
      "@context": "http://schema.org",
      "@type": "ViewAction",
      "name": "View in Wunderlist",
      "target": ["https://wunderlist.com/lists/1101/overview"]
    }
  ]
}
A message card with an action button

Color

Developers can also control a color bar by setting themeColor to a color hex code. This bar appears to the left of the card’s content, and is primarily used to indicate status to the user.

{
  "text": " Remember to [get milk at the store!](https://wunderlist.com/lists/1101/)",
  "title": "Today:",
  "themeColor": "E81123",
  "potentialAction": [
    {
      "@context": "http://schema.org",
      "@type": "ViewAction",
      "name": "View in Wunderlist",
      "target": ["https://wunderlist.com/lists/1101/overview"]
    }
  ]
}
A message card with a color bar

Reference

Use Markdown for formatting

Every string property in a connector card is handled as Markdown by default. Content of these properties can be formatted using basic Markdown markup (headings, bold, italic, etc.). Do NOT use HTML markup in these properties.

Connector Card

Attribute Type Description
summary SimpleString* A string used for summarizing card content. This will be shown as the message subject. This is required if the text parameter isn't populated.
text String The main text of the card. This will be rendered below the sender information and optional title, and above any sections or actions present.
title SimpleString* A title for the Connector message. Shown at the top of the message.
themeColor Color Hex Value ex: #737373 Accent color used for branding or indicating status in the card.
sections Section[] Contains a list of sections to display in the card
entities Schema.org/Object[] This property will not be used to generate the displayed Card, but other experiences may consume the Schema.org content included here.
potentialAction Schema.org/ViewAction[] This array of Schema.org/ViewAction objects will power the action links found at the bottom of the card.

***** SimpleString is a plaintext String with no added Markdown.

Section

A section is a canvas to show richer content than what can be represented in the just the title and text of the card. A section can contain text and images, or the activity and facts fields can be used to highlight key events and details. These sections are passed via the sections array in the payload, and will be rendered in the order of array position.

The content in a section is displayed in the following order (top to bottom): * title * text * activityTitle, activitySubtitle, activityText * facts * images * actions

Any section variables that are not filled in will not be displayed.

Attribute Type Description
title String Title of the section
activityTitle String Title of the event or action. Often this will be the name of the "actor".
activitySubtitle String A subtitle describing the event or action. Often this will be a summary of the action.
activityImage URL to image or a data URI with the base64-encoded image inline. An image representing the action. Often this is an avatar of the "actor" of the activity.
activityText String A full description of the action.
facts Fact[] An array of facts, displayed as key-value pairs.
images Image[] An array of images that will be displayed at the bottom of the section.
text String Optional text that will appear before the activity.
markdown bool Set this to false to disable markdown parsing on this section's content. Markdown parsing is enabled by default.
potentialAction Schema.org/ViewAction[] This array of Schema.org/ViewAction objects will power the action links found at the bottom of the section

Activity

Notifications for actions on events can be gracefully constructed with activity parameters.

activityTitle, activitySubtitle, activityText

activityTitle, activitySubtitle, and activityText are three text fields that are displayed in-order from top to bottom. When an activityImage is passed, these text fields will align next to the image. These fields are all markdown compatible.

activityImage

An activityImage is a URL to an image or a data URI with the base64-encoded image inline. The image is related to the activity. It is often the avatar of the 'actor' of the activity. The activityImage will be displayed next to the activityTitle, activitySubtitle, and activityText.

Fact

Facts are simple name value pairs that will appear in a list. These are set as a list in the facts field of the Section object.

Attribute Type Description
name SimpleString* Name of the fact
value String Value of the fact

***** SimpleString is a plaintext String with no added Markdown.

Image

An image object contains an image url. Connectors supports jpg, gif, and png formats. Images are displayed at the bottom of a section. Images are passed via the images array from within a section.

Attribute Type Description
title SimpleString* Alt-text for the image (optional)
image URL A URL to the image file or a data URI with the base64-encoded image inline.

Actions

Actions can also be placed inside a section, where they will be displayed at the bottom of the section. They follow the same schema.org format as the top-level actions.

Example message with multiple sections

A connector card with multiple sections
{
  "summary": "Miguel Garcia commented on Trello",
  "title": "Project Tango",
  "sections": [
    {
      "activityTitle": "Miguel Garcia commented",
      "activitySubtitle": "On Project Tango",
      "activityText": "\"Here are the designs \"",
      "activityImage": "https://connectorsdemo.azurewebsites.net/images/MSC12_Oscar_002.jpg"
    },
    {
      "title": "Details",
      "facts": [
        {
          "name": "Labels",
          "value": "Designs, redlines"
        },
        {
          "name": "Due date",
          "value": "Dec 7, 2016"
        },
        {
          "name": "Attachments",
          "value": "[final.jpg](https://connectorsdemo.azurewebsites.net/images/WIN14_Jan_04.jpg)"
        }
      ]
    },
      {
        "title": "Images",
        "images": [
          {
          "image":"https://connectorsdemo.azurewebsites.net/images/MicrosoftSurface_024_Cafe_OH-06315_VS_R1c.jpg"
          },
          {
          "image":"https://connectorsdemo.azurewebsites.net/images/WIN12_Scene_01.jpg"
          },
          {
          "image":"https://connectorsdemo.azurewebsites.net/images/WIN12_Anthony_02.jpg"
          }
        ]
      }
  ],
  "potentialAction": [
    {
      "@context": "http://schema.org",
      "@type": "ViewAction",
      "name": "View in Trello",
      "target": [
        "https://trello.com/c/1101/"
      ]
    }
  ]
}

Response Codes

The following HTTP response codes are returned to the sender in the given scenarios.

Response Code Description Details
200 Ok A well-formed request is sent to an existing webhook. The request contains a valid payload, and has a valid corresponding webhook configuration.
400 Bad Request An incorrectly-formed request is sent to a webhook that exists. The payload could contain non-parseable JSON, incorrect JSON values (e.g. expected a String, got an array), incorrect content-type, etc..
404 Not Found A request is sent to a webhook that does not exist.
413 Payload Too Large A request is sent to a webhook that is too large in size for processing.
429 Too Many Requests Client is sending too many requests and Office 365 is throttling the requests to a webhook.

Message Headers

Messages sent to Connectors webhooks must include Content-Type: application/json in the HTML header.