SharePoint List Formatting
Back to column formats
Column formattingSharePoint Online

Multi-Person Teams Chat Link

This sample demonstrates creating a deep link to a Microsoft Teams chat. This format works both within Microsoft Teams and within SharePoint Online.

Get this format View on GitHub

Shared by Chris Kent
Updated Jan 23, 2020

Multi-Person Teams Chat Link formatting preview
Sample preview · View original image

Copy. Apply. Make it yours.

Get this format

1 definition

Review the requirements below, then paste this JSON into the matching formatting panel. Show me where.

Use your list's internal column names and replace any tenant-specific URLs or flow IDs. Formatting is presentation, not a way to secure data.

Column formatting
Download JSON
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json",
  "elmType": "a",
  "attributes": {
    "href": "='https://teams.microsoft.com/l/chat/0/0?users=' + join(@currentField.email,',') + '&topicName=' + [$FileLeafRef] + '&message=Neigh?'",
    "class": "ms-fontColor-themePrimary ms-fontColor-themeDark--hover",
    "title": "='Start a chat with ' + join(@currentField.title, ', ')"
  },
  "style": {
    "text-decoration": "none"
  },
  "children": [
    {
      "elmType": "span",
      "attributes": {
        "iconName": "SurveyQuestions"
      },
      "style": {
        "padding-right": "4px"
      }
    },
    {
      "elmType": "span",
      "txtContent": "Ask a Question"
    }
  ]
}
View sourceLink to this definitionmulti-person-teams-chat-link.json

From the contributor

How to use this sample

Summary

This sample demonstrates creating a deep link to a Microsoft Teams chat. This format works both within Microsoft Teams and within SharePoint Online.

screenshot of the sample in Microsoft Teams

screenshot of the sample

The Microsoft Teams chat link is broken down into a base URL https://teams.microsoft.com/l/chat/0/0 and then query parameters to set portions of the chat:

  • users - A comma-separated list of Azure AD UserPrincipalName values (email addresses in this case)
    • This format uses the join operator to combine all the email values for the chosen people
  • topicName - An optional parameter for the chat's display name (only applies when there are 3+ users)
  • message - An optional parameter that sets a starter message in the chat box (doesn't send automatically)

The link is built using the + operator to combine the strings together using an expression.

Differences with Microsoft Teams

There are a few key differences when it comes to creating formats to be used within Microsoft Teams compared to modern list views:

  • Subtle differences in CSS defaults. For instance, removing the vertical-align style prop on the image will make no difference in a modern list view but will cause problems within Microsoft Teams
  • Relative links resolve differently. Always use the @currentWeb token to ensure resources are loading from where you expect. Relative links will try and load from teams.microsoft.com when viewed in Teams which is often what you don't want.
  • Theme color classes will behave differently. These are respected within list views, but are not yet supported within Microsoft Teams (see screenshots above). Using direct color values will prevent your formats from being theme sensitive/safe, but the values will be consistent between the environments.

View requirements

  • This format can be applied to a Multi-Select Person column
  • This format uses operators only available in SharePoint Online and cannot be used in SharePoint 2019
  • This format expects to be applied to a document library (relies on [$FileLeafRef] but could easily be adapted for a List by using a different field such as [$Title])

Sample

Solution Author(s)
multi-person-teams-chat-link.json Chris Kent

Version history

Version Date Comments
1.0 January 23, 2020 Initial release

Disclaimer

THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

Additional notes

Keep exploring

More formats like this

Missing Information Callout

The Missing Information Callout column formatter provides a clear, accessible visual indicator when a SharePoint list column contains no value.

Explore format

Publishing Status

Sample contains an example of using the modulo math expression for highlighting 'published', 'published with draft' and 'draft with no published versions' of pages

Explore format

File Preview Callout with the embed Action

This sample demonstrates how to display a file preview from a document library or Site Pages inside a callout using the embed action. This allows users to view file contents without leaving the current page.

Explore format