Прямая ссылка на чат Teams

  • Статья

Вы можете создать прямую ссылку на чат Teams, например, чтобы начать новый чат, перейти в беседу на канале и получить доступ к файлу в канале.

В этой статье вы узнаете, как создать:

Вы можете переходить к или создавать личные чаты между пользователями с помощью клиентской библиотеки JavaScript (TeamsJS) Microsoft Teams, указав набор участников. Если чат с указанными участниками не существует, пользователь будет перенаправлен в новый пустой чат.

Когда пользователь создает новый чат с помощью глубокой ссылки, Teams создает новый чат в состоянии черновика, пока пользователь не отправит первое сообщение. Вы также можете указать имя чата, если он еще не существует, а также текст, который следует вставить в поле создания пользователя. Считайте это ярлыком для пользователя, который выполняет вручную переход к чату или создает его, а затем создает сообщение.

В качестве примера использования, если вы извлеките данные профиля пользователя Microsoft 365 из бота в качестве карта, эта прямая ссылка может позволить пользователю приложения легко общаться с этим человеком.

Вы можете настроить глубокие ссылки для запуска нового чата одним из следующих двух способов:

Рекомендуется использовать типизированные API, но также можно использовать следующий формат для созданной вручную прямой ссылки, которую можно использовать в боте, соединителе или карточке расширения для сообщений:

https://teams.microsoft.com/l/chat/0/0?tenantId=<tenantId>&users=<user1>,<user2>,...&topicName=<chat name>&message=<precanned text>

Чтобы использовать эту прямую ссылку с ботом, укажите прямую ссылку в качестве целевого URL-адреса в кнопке карта или коснитесь действия с помощью openUrl типа действия.

Параметры запроса:

  • users: разделенный запятыми список идентификаторов пользователей, представляющих участников чата. Пользователь, выполняющий действие, всегда включен в качестве участника. В настоящее время параметр User ID поддерживает Microsoft Entra UserPrincipalName, например только адрес электронной почты.
  • topicName: необязательный параметр для отображаемого имени чата, если в чате есть три или более пользователей. Если это поле не указано, отображаемое имя чата основывается на именах участников.
  • message: необязательное поле для текста сообщения, которое вы хотите вставить в поле создания текущего пользователя приложения, пока чат находится в состоянии черновика.

Пример: https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow

В следующем примере показано, как открыть сообщение чата для группы участников с исходным сообщением. Вы можете настроить прямую ссылку на существующий или новый чат. Если чат уже существует, откроется прямая ссылка в этом чате.

if(chat.isSupported()) {
    const chatPromise = chat.openGroupChat({ users: ["joe@contoso.com","bob@contoso.com"], topic: "Prep For Meeting Tomorrow", message: "Hi folks kicking off chat about our meeting tomorrow"});
    chatPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Чтобы перейти к определенной беседе чата в Teams, используйте следующий формат глубокой ссылки:

https://teams.microsoft.com/l/chat/<chatId>/conversations

Параметр запроса — chatId, который представляет идентификатор чата беседы. Поддерживаемый формат для chatId — 19:xxx.

Пример: https://teams.microsoft.com/l/chat/19:c6d70e392a384916c3262b15406d763e@thread.v2/conversations

Для перехода к определенной беседе в потоке канала можно использовать следующий формат глубокой ссылки:

https://teams.microsoft.com/l/message/<channelId>/<parentMessageId>?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=<parentMessageId>&teamName=<teamName>&channelName=<channelName>&createdTime=<createdTime>

Параметры запроса:

  • channelId: идентификатор канала беседы. Например, 19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2.
  • tenantId: идентификатор клиента, например 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • groupId: идентификатор группы файла. Например, 3606f714-ec2e-41b3-9ad1-6afb331bd35d.
  • parentMessageId: идентификатор родительского сообщения в беседе.
  • teamName: имя команды.
  • channelName: название канала команды.

Примечание.

Вы можете увидеть channelId и groupId в URL-адресе канала.

Пример: https://teams.microsoft.com/l/message/<channelId>/1648741500652?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=1648741500652&teamName=<teamName>&channelName=<channelName>&createdTime=1648741500652

Используйте следующий формат глубокой ссылки для перехода пользователя к сообщению в личном или групповом чате в Teams:

https://teams.microsoft.com/l/message/{chatId}/{messageId}?tenantId=<tenantId>?context={"contextType":"chat"}

Пример: https://teams.microsoft.com/l/message/19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces/1563480968434?context=%7B%22contextType%22:%22chat%22%7D

Параметры запроса:

  • chatId: идентификатор чата беседы. Поддерживаемый формат — chatId 19: xxx. Например, 19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces.
    Приложения могут считывать идентификатор чата через контекст приложения в Teams, входящие полезные данные боту или через API Microsoft Graph.

    Примечание.

    Для общения с ботом в входящие полезные данные для бота содержат идентификатор беседы в формате a:xxx.

  • messageId: уникальный идентификатор каждого сообщения в чате. Когда бот публикует сообщение в чате messageId , возвращается . Вы также можете получить через messageIdAPI Microsoft Graph. Например, 1563480968434.
  • context: укажите contextType в качестве чата.

Пример: http://teams.microsoft.com/l/message/19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces/1563480968434?context=%7B%22contextType%22:%22chat%22%7D

Чтобы перейти к определенной команде, используйте следующий формат глубокой ссылки:

https://teams.microsoft.com/l/team/<channelId>/conversations?groupId=<groupId>&tenantId=<tenantId>

Параметры запроса:

  • channelId: идентификатор канала беседы (в кодировке URL-адреса). Например, 19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2.
  • groupId: идентификатор группы файла. Например, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: идентификатор клиента, например 72f988bf-86f1-41af-91ab-2d7cd011db47.

Примечание.

Вы можете получить channelId и groupId в URL-адресе от команды.

Пример: https://teams.microsoft.com/l/team/19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2/conversations?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

Для перехода по определенным каналам можно использовать следующие форматы глубоких ссылок:

  • Стандартный канал: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>

    Пример: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

  • Частный канал: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true

    Пример: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true

  • Общий канал: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true&allowXTenantAccess=true

    Пример: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true&allowXTenantAccess=true

Параметры запроса:

  • channelId: идентификатор канала беседы (в кодировке URL-адреса). Например, 19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2.
  • channelName: имя канала команды (в кодировке URL-адреса). Например, My%20example%20channel.
  • groupId: идентификатор группы. Например, 72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: идентификатор клиента, например 72f988bf-86f1-41af-91ab-2d7cd011db47.
  • ngc: указывает канал следующего поколения. Для частных каналов необходимо задать значение true.
  • allowXTenantAccess: указывает канал, к которому можно получить доступ через границы клиента. Для общих каналов необходимо задать значение true.

В боте, соединителе или расширении сообщений карта для настройки глубокой ссылки для подключения к файлу в канале можно использовать следующий формат глубокой ссылки:

https://teams.microsoft.com/l/file/<fileId>?tenantId=<tenantId>&fileType=<fileType>&objectUrl=<objectUrl>&baseUrl=<baseUrl>&serviceName=<Name>&threadId=<threadId>&groupId=<groupId>

Параметры запроса:

  • fileId: Идентификатор уникального документа Sharepoint Online, также известный как sourcedoc. Например, 1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: идентификатор клиента, например 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • fileType: поддерживаемый тип файла, например DOCX, PPTX, XLSX и PDF.
  • objectUrl: URL-адрес объекта файла. Представлено в формате https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext. Например, https://microsoft.sharepoint.com/teams/(filepath).
  • baseUrl: базовый URL-адрес файла. Представлено в формате https://{tenantName}.sharepoint.com/sites/{TeamName}. Например, https://microsoft.sharepoint.com/teams.
  • serviceName: имя службы, идентификатор приложения Например, teams.
  • threadId: threadID — это идентификатор команды, в которой хранится файл. Это необязательно и не может быть установлено для файлов, хранящихся в пользовательской папке OneDrive. Например, 19:<f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype>.
  • groupId: идентификатор группы файла. Например, ae063b79-5315-4ddb-ba70-27328ba6c31e.

Примечание.

  • Вы можете увидеть threadId и groupId в URL-адресе канала.
  • В новом клиенте Teams формат глубокой ссылки, использующий objectURL для файла в канале, не поддерживается и используется objectUrl в формате deep link.

Следующий пример формата иллюстрирует глубокую ссылку на файлы:

https://teams.microsoft.com/l/file/5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80?tenantId=0d9b645f-597b-41f0-a2a3-ef103fbd91bb&fileType=pptx&objectUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform%2FShared%20Documents%2FFC7-%20Bot%20and%20Action%20Infra%2FKaizala%20Actions%20in%20Adaptive%20Cards%20-%20Deck.pptx&baseUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform&serviceName=teams&threadId=19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype&groupId=ae063b79-5315-4ddb-ba70-27328ba6c31e

Сериализация этого объекта

{
fileId: "5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80",
tenantId: "0d9b645f-597b-41f0-a2a3-ef103fbd91bb",
filetype: = "pptx",
objectUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform/Shared Documents/FC7- Bot and Action Infra/Kaizala Actions in Adaptive Cards - Deck.pptx",
baseUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform",
serviceName: "teams",
threadId: = "19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype",
groupId: "ae063b79-5315-4ddb-ba70-27328ba6c31e"
}

Пример кода

Название примера Описание .NET Node.js
Прямая ссылка, используюющая идентификатор subentity В этом примере показано, как использовать прямую ссылку из чата бота на вкладку, используюющую идентификатор subentity. Здесь также показаны подробные ссылки для:
— Переход к приложению
— Переход к чату
— Открытие диалогового окна профиля
— Открытие диалогового окна планирования		 Просмотр Просмотр