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

Get started with Office 365 Connector Cards in Outlook and Microsoft Teams

Creating messages through Office 365 Connectors in Outlook

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. Let's try posting some basic cards to a group.

You'll need an Office 365 subscription to proceed. If you do not have an Office 365 subscription you can get a one year FREE Office 365 Subscription under the Office 365 Developer Program. Alternately, if you have an existing MSDN subscription, you can activate your free Office 365 benefit.

Get the group's connector webhook URL

  1. Log on to the Office 365 Mail app at https://outlook.office.com. Select a group to test connector cards with.

    A screenshot of the navigation menu in OWA with a group selected

  2. Choose the Connectors link in the group menu.

    A screenshot of the groups menu with the Connectors link

  3. Locate the Incoming Webhook connector in the list of available connectors, and choose Add.

    A screenshot of the Incoming Webhook item in the available connectors list

  4. Enter a name for this connector and choose Create.

    A screenshot of the Incoming Webhook creation page

  5. Copy the webhook URL that is displayed and save it. Choose Done.

    A screenshot of the Incoming Webhook URL

The webhook URL should look simliar to the following:

https://outlook.office365.com/webhook/a1269812-6d10-44b1-abc5-b84f93580ba0@9e7b80c7-d1eb-4b52-8582-76f921e416d9/IncomingWebhook/3fdd6767bae44ac58e5995547d66a4e4/f332c8d9-3397-4ac5-957b-b8e3fc465a8c

Post a card to the webhook

For this part of the exercise, you'll need cURL. It's assumed that you have this installed and are familiar with basic usage.

  1. From the command line, enter the following cURL command:

    curl -H "Content-Type: application/json" -d "{\"text\": \"Hello World!\"}" <YOUR WEBHOOK URL>
    
  2. If the POST succeeds, you should see a simple 1 output by cURL.

  3. Check the group in Outlook or the Office 365 Mail app. You should see the new card posted to the group.

A screenshot of the Hello World! message card in the Office 365 Mail app

Posting more complex cards

Now let's look at how you can post richer, more complex cards. Let's add a title, color, and hyperlink to the next card.

  1. From the command line, enter the following cURL command:

    curl -H "Content-Type: application/json" -d "{\"title\": \"Learn about Office 365 Connectors\", \"text\": \"Visit the [Outlook Dev Portal](https://dev.outlook.com) to learn more about Office 365 Connectors!\", \"themeColor\": \"EA4300\"}" <YOUR WEBHOOK URL>
    
  2. If the POST succeeds, you should see a simple 1 output by cURL.

  3. Check the group in Outlook or the Office 365 Mail app. You should see the new card posted to the group.

A screenshot of the Hello World! message card in the Office 365 Mail app

The JSON payload sent this time differs from the "Hello World!" card we sent before in a few key areas:

  • It includes a title property.
  • The text property includes Markdown syntax for making the text "Outlook Dev Portal" link to https://dev.outlook.com.
  • It includes a themeColor property, which controls the color displayed down the side of the card.

Let's build on this card format and add an action. An action is a button that renders in the card.

  1. From the command line, enter the following cURL command:

    curl -H "Content-Type: application/json" -d "{\"title\": \"Learn about Office 365 Connectors\", \"text\": \"Visit the [Outlook Dev Portal](https://dev.outlook.com) to learn more about Office 365 Connectors!\", \"themeColor\": \"EA4300\", \"potentialAction\": [{\"@context\": \"https://schema.org\", \"@type\": \"ViewAction\", \"name\": \"Open Outlook Dev Center\", \"target\": [\"https://dev.outlook.com\"]}]}" <YOUR WEBHOOK URL>
    
  2. If the POST succeeds, you should see a simple 1 output by cURL.

  3. Check the group in Outlook or the Office 365 Mail app. You should see the new card posted to the group.

A screenshot of the Hello World! message card in the Office 365 Mail app

Creating messages through Office 365 Connectors in Microsoft Teams

Connectors use webhooks to create Connector Card messages within Microsoft Team. Developers can create these cards by sending an HTTP request with a simple JSON payload to a Microsoft Team webhook address. Let's try posting some basic cards to a group.

Get the team's connector webhook URL

  1. Log on to Microsoft Teams at https://teams.microsoft.com. Select the channel to test connector cards with.

  2. In the Channel list on the left, click on the ... and select Connectors.

    A screenshot of the Microsoft Teams menu with the Connectors link

  3. Locate the Incoming Webhook connector in the list of available connectors, and choose Add.

    A screenshot of the Incoming Webhook item in the available connectors list

  4. Enter a name for this connector and choose Create.

    A screenshot of the Incoming Webhook creation page

  5. Copy the webhook URL that is displayed and save it. Choose Done.

    A screenshot of the Incoming Webhook URL

Post cards

You can use the same method in Post a card to the webhook and Posting more complex cards to posts cards to your Microsoft Teams webhook.

Next Steps

Now that you're familiar with the basics of posting message cards to a group's webhook, you can find out more about Office 365 Group Connectors.