-
Notifications
You must be signed in to change notification settings - Fork 303
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: adding the basic mgt-chat docs (#2571)
* Adding the basic Chat docs * Update aka.ms link for components docs
- Loading branch information
1 parent
2f06e01
commit 5cf7961
Showing
3 changed files
with
257 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,122 @@ | ||
# Microsoft Graph Toolkit Chat Components | ||
|
||
[![npm](https://img.shields.io/npm/v/@microsoft/mgt-chat/next.mgt-chat?style=for-the-badge)](https://www.npmjs.com/package/@microsoft/mgt-chat) | ||
|
||
> Note: The Microsoft Graph Toolkit Chat Components are in Private Preview and are subject to change. The use of these components in production applications is not supported. | ||
The [Microsoft Graph Toolkit (mgt)](https://aka.ms/mgt) library is a collection of authentication providers and UI components powered by Microsoft Graph. | ||
|
||
The `@microsoft/mgt-chat` package contains all chat components that allow to build chat-based applications with React. | ||
|
||
[See docs for full documentation](https://aka.ms/mgt/docs) | ||
|
||
[See docs for chat components](https://aka.ms/mgt/docs/chat/components) | ||
|
||
## Getting started with the Graph Toolkit chat components | ||
|
||
Use this guide to get started with using the Microsoft Graph Toolkit Chat Components. Some of the steps highlights in this guide are temporary and will evolve with the future preview versions of the components. | ||
|
||
### Install the Graph Notification Broker | ||
|
||
To start, the Chat Components require a server side dependency to help with receiving live notifications from the service. This helps with getting new messages, roster changes, etc. This component is the [Graph Notification Broker](https://github.com/microsoft/GraphNotificationBroker#graph-notification-broker). | ||
|
||
To install the Graph Notification Broker, refer to this [deployment guide](https://github.com/microsoft/GraphNotificationBroker/blob/main/docs/deployment-guide.md#Deployment-Guide). | ||
|
||
From this deployment, you will need to keep track of 3 created artifacts: | ||
|
||
* The URL of the provisioned Azure Function | ||
* The ID of the Backend App Registration | ||
* The ID of the Frontend App Registration | ||
|
||
### Install the necessary dependencies | ||
|
||
In your React app where you want to add the Microsoft Graph Toolkit Chat Components, you will need to install our dependencies: | ||
|
||
```bash | ||
npm install @microsoft/[email protected] | ||
npm install @microsoft/mgt-react | ||
npm install @microsoft/mgt-msal2-provider | ||
``` | ||
|
||
### Configure the broker settings and authentication | ||
|
||
At the root of your component hierarchy (usually in `index.tsx`), configure the broker settings with the previously noted values. You will also configure the authentication to enable seemless integration with both the Graph Notification Broker and with Microsoft Graph. | ||
|
||
```tsx | ||
import { Providers } from '@microsoft/mgt-react'; | ||
import { Msal2Provider } from '@microsoft/mgt-msal2-provider'; | ||
import { allChatScopes, brokerSettings } from '@microsoft/mgt-chat'; | ||
|
||
brokerSettings.functionHost = '%URL_AZURE_FUNCTION%'; | ||
brokerSettings.appId = '%BACKEND_APP_ID%'; | ||
|
||
Providers.globalProvider = new Msal2Provider({ | ||
clientId: '%FRONTEND_APP_ID%', | ||
scopes: allChatScopes | ||
}); | ||
``` | ||
|
||
### Add the components to your code | ||
|
||
You have all the necessary settings in place to add the Microsoft Graph Toolkit Chat Components to your application. To add the components, just do the following: | ||
|
||
```tsx | ||
import React, { memo, useCallback, useState } from 'react'; | ||
import { Login } from '@microsoft/mgt-react'; | ||
import { Chat, NewChat } from '@microsoft/mgt-chat'; | ||
|
||
export const App: React.FunctionComponent = () => { | ||
const [chatId, setChatId] = useState<string>(); | ||
|
||
const [showNewChat, setShowNewChat] = useState<boolean>(false); | ||
const onChatCreated = useCallback((chat: GraphChat) => { | ||
setChatId(chat.id); | ||
setShowNewChat(false); | ||
}, []); | ||
|
||
return ( | ||
<Login /> | ||
<button onClick={() => setShowNewChat(true)}>New Chat</button> | ||
{showNewChat && ( | ||
<NewChat | ||
onChatCreated={onChatCreated} | ||
onCancelClicked={() => setShowNewChat(false)} | ||
mode="auto" | ||
hideTitle={true} | ||
title="Create a new chat" | ||
/> | ||
)} | ||
|
||
{chatId && <Chat chatId={chatId} />} | ||
); | ||
} | ||
``` | ||
|
||
### Review existing samples | ||
|
||
We are providing simple apps that provides all the necessary elements to have a fully working application with our Chat Components. | ||
|
||
* [Our basic `react-chat` application](../../samples/react-chat) | ||
* [Our hero `react-contoso` application](../../samples/react-contoso) | ||
|
||
### Known issues | ||
|
||
* When using the chat components, users need to login twice because it requires to acquire tokens to both Microsoft Graph and the Graph Notification Broker | ||
|
||
## Contribute | ||
|
||
We enthusiastically welcome contributions and feedback. Please read our [wiki](https://github.com/microsoftgraph/microsoft-graph-toolkit/wiki) and the [contributing guide](../../CONTRIBUTING.md) before you begin. | ||
|
||
## Feedback and Requests | ||
|
||
For general questions and support, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/microsoft-graph-toolkit) where questions should be tagged with `microsoft-graph-toolkit` | ||
|
||
Please use [GitHub Issues](https://github.com/microsoftgraph/microsoft-graph-toolkit/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) for bug reports and feature requests. We highly recommend you browse existing issues before opening new issues. | ||
|
||
## License | ||
|
||
All files in this GitHub repository are subject to the [MIT license](https://github.com/microsoftgraph/microsoft-graph-toolkit/blob/main/LICENSE). This project also references fonts and icons from a CDN, which are subject to a separate [asset license](https://static2.sharepointonline.com/files/fabric/assets/license.txt). | ||
|
||
## Code of Conduct | ||
|
||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
--- | ||
title: "Chat component in Microsoft Graph Toolkit" | ||
description: "The Chat component enables the user to have full 1:1 or group conversations. It works with any conversation happening in Microsoft Teams." | ||
ms.localizationpriority: medium | ||
author: sebastienlevert | ||
--- | ||
|
||
# Chat component in Microsoft Graph Toolkit | ||
|
||
[!IMPORTANT] This component is in Preview and is subject to change. The use of these components in production applications is not supported. | ||
|
||
[!NOTE] This component is only available as a React component but this is subject to change. | ||
|
||
The Chat component enables the user to have full 1:1 or group conversations. It works with any conversation happening in Microsoft Teams. | ||
|
||
## Example | ||
|
||
The following example displays a signed-in user's conversation using the `mgt-chat` component. You can use the code editor to see how [properties](#properties) change the behavior of the component. | ||
|
||
<iframe src="https://mgt.dev/iframe.html?id=components-mgt-chat--chat&source=docs" height="500"></iframe> --> | ||
|
||
[Open this example in mgt.dev](https://mgt.dev/?path=/story/components-mgt-chat--chat&source=docs) | ||
|
||
## Properties | ||
|
||
| Attribute | Property | Description | | ||
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ | | ||
| chat-id | chatId | A string ID to set the 1:1 or group conversation to render. Required. | | ||
|
||
The following example shows a conversation with ID _19:[email protected]2_. | ||
|
||
```tsx | ||
<Chat chatId={'19:[email protected]'} /> | ||
``` | ||
|
||
## CSS custom properties | ||
|
||
The `mgt-chat` component does not define CSS custom properties. | ||
|
||
## Events | ||
|
||
The `mgt-chat` component doesn't offer any events. | ||
|
||
## Templates | ||
|
||
The `mgt-chat` component doesn't offer any template to override. | ||
|
||
## Microsoft Graph permissions | ||
|
||
This control uses the following Microsoft Graph APIs and permissions. | ||
|
||
| Configuration | Permission | API | | ||
| - | - | - | | ||
| `chatId` is set | Chat.ReadBasic, Chat.Read, ChatMessage.Read, Chat.ReadWrite, ChatMember.ReadWrite | [/chats/{id}/messages](https://learn.microsoft.com/graph/api/chat-list-messages?view=graph-rest-1.0&tabs=http), [/chats/{id}/messages](https://learn.microsoft.com/graph/api/chat-post-messages?view=graph-rest-1.0&tabs=http), [/chats/{id}/messages/{messageId}](https://learn.microsoft.com/graph/api/chatmessage-update?view=graph-rest-1.0&tabs=http), [/me/chats/{id}/messages/{messageId}/softDelete](https://learn.microsoft.com/graph/api/chatmessage-softdelete?view=graph-rest-1.0&tabs=http), [/chats/{id}/members/{membershipId}](https://learn.microsoft.com/graph/api/chat-delete-members?view=graph-rest-1.0&tabs=http), [/chats/{id}/members](https://learn.microsoft.com/graph/api/chat-post-members?view=graph-rest-1.0&tabs=http), [/chats/{id}/messages/{messageId}/hostedContents/{hostedContentId}](https://learn.microsoft.com/graph/api/chatmessagehostedcontent-get?view=graph-rest-1.0&tabs=http), [/chats/{id}](https://learn.microsoft.com/graph/api/chat-patch?view=graph-rest-1.0&tabs=http) | | ||
|
||
## Authentication | ||
|
||
The tasks component uses the global authentication provider described in the [authentication documentation](../providers/providers.md). | ||
|
||
## Cache | ||
|
||
The `mgt-tasks` component doesn't cache any data. | ||
|
||
## Localization | ||
|
||
The `mgt-tasks` component doesn't expose any localization variables. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,69 @@ | ||
--- | ||
title: "New Chat component in Microsoft Graph Toolkit" | ||
description: "The New Chat component allows user to create new 1:1 or group conversations in Microsoft Teams." | ||
ms.localizationpriority: medium | ||
author: sebastienlevert | ||
--- | ||
|
||
# New Chat component in Microsoft Graph Toolkit | ||
|
||
[!IMPORTANT] This component is in Preview and is subject to change. The use of these components in production applications is not supported. | ||
|
||
[!NOTE] This component is only available as a React component but this is subject to change. | ||
|
||
The New Chat component allows user to create new 1:1 or group conversations in Microsoft Teams. | ||
|
||
## Example | ||
|
||
The following example displays a signed-in user's conversation using the `mgt-new-chat` component. You can use the code editor to see how [properties](#properties) change the behavior of the component. | ||
|
||
<iframe src="https://mgt.dev/iframe.html?id=components-mgt-new-chat--new-chat&source=docs" height="500"></iframe> --> | ||
|
||
[Open this example in mgt.dev](https://mgt.dev/?path=/story/components-mgt-new-chat--new-chat&source=docs) | ||
|
||
## Properties | ||
|
||
| Attribute | Property | Description | | ||
| - | - | - | | ||
| hide-title | hideTitle | A Boolean to set the component interface to hide its title. Default is `false`. | | ||
| title | title | Value of the title displayed in the component. | | ||
| mode | mode | Set to `oneOnOne`, `group` or `auto`. Default is `auto`. | | ||
|
||
## CSS custom properties | ||
|
||
The `mgt-new-chat` component does not define CSS custom properties. | ||
|
||
## Events | ||
|
||
The following events are fired from the component. | ||
|
||
Event | When is it emitted | Custom data | Cancelable | Bubbles | Works with custom template | ||
------|-------------------|--------------|:-----------:|:---------:|:---------------------------:| | ||
`onChatCreated` | Fired when a new chat thread is created. | The `chat` object that was created as a Microsoft Graph [chat](https://learn.microsoft.com/graph/api/resources/chat?view=graph-rest-1.0#json-representation). | No | No | No | | ||
`onCancelClicked` | Fired when user cancels the chat thread creation. | None | No | No | No | | ||
|
||
For more information about handling events, see [events](../customize-components/events.md). | ||
|
||
## Templates | ||
|
||
The `mgt-chat` component doesn't offer any template to override. | ||
|
||
## Microsoft Graph permissions | ||
|
||
This control uses the following Microsoft Graph APIs and permissions. | ||
|
||
| Configuration | Permission | API | | ||
| - | - | - | | ||
| Default | Chat.Create, ChatMessage.Send | [/chats](https://learn.microsoft.com/graph/api/chat-post?view=graph-rest-1.0&tabs=http), [/chats/{id}/messages](https://learn.microsoft.com/graph/api/chat-post-messages?view=graph-rest-1.0&tabs=http) | | ||
|
||
## Authentication | ||
|
||
The tasks component uses the global authentication provider described in the [authentication documentation](../providers/providers.md). | ||
|
||
## Cache | ||
|
||
The `mgt-tasks` component doesn't cache any data. | ||
|
||
## Localization | ||
|
||
The `mgt-tasks` component doesn't expose any localization variables. |