Skip to content

Commit eb74055

Browse files
dieterd-msftdieterd-msft
authored
PCF Control (#441)
* Add Webchat PCF control for Canvas Apps * Add Webchat PCF control for Canvas Apps
1 parent af20fd1 commit eb74055

13 files changed

Lines changed: 1162 additions & 0 deletions

‎PCFControls/ChatControl/README.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# ChatControl - Power Apps Component Framework (PCF) Control
2+
3+
This sample contains a [PCF](https://learn.microsoft.com/power-apps/developer/component-framework/overview) control that integrates Microsoft Copilot Studio agents into [Canvas Apps](https://learn.microsoft.com/power-apps/maker/canvas-apps/getting-started). It leverages the ReactWebChat component with the [Fluent UI theme pack](https://github.com/microsoft/BotFramework-WebChat#experimental-fluent-ui-theme-pack) and the [Microsoft 365 Agents SDK for TypeScript](https://github.com/microsoft/Agents-for-js) to establish a secure connection with a Copilot Studio agent configured with ['Authenticate with Microsoft'](https://learn.microsoft.com/microsoft-copilot-studio/configuration-end-user-authentication#authenticate-with-microsoft).
4+
5+
## Overview
6+
7+
The ChatControl provides a seamless way to embed Microsoft Copilot Studio agents directly into your Power Apps **Canvas Apps**. It features a modern, responsive chat interface with support for file uploads, custom styling, and real-time message handling.
8+
9+
## Features
10+
11+
- **Authentication**: Built-in single-sign-on (SSO) support for secure agent access
12+
- **Modern Chat UI**: Clean, responsive interface with Bot Framework WebChat and Fluent theme support
13+
- **Customizable Appearance**: Configurable style options to match your application's design
14+
- **New Conversation Support**: Users can start fresh conversations without leaving the page
15+
- **Fluent UI Styling**: Uses the Fluent UI theme pack for a native Microsoft 365 look and feel
16+
- **Copilot Studio Integration**: Direct integration with Microsoft Copilot Studio agents via authenticated connections
17+
- **Message interaction**: Send and receive messages from your app to interact with the agent
18+
- **Event Support**: Send custom events to agents, for example to initialize variables at the beginning of a chat
19+
20+
## Prerequisites
21+
22+
Before you begin, ensure you have the following:
23+
24+
1. **Published Copilot Studio Agent**
25+
- Agent must be configured with ['Authenticate with Microsoft'](https://learn.microsoft.com/microsoft-copilot-studio/configuration-end-user-authentication#authenticate-with-microsoft) authentication
26+
- Agent should be published and accessible
27+
28+
2. **Azure Portal Access**
29+
- Required for creating and configuring app registrations
30+
- Permissions to create new app registrations in your Azure AD tenant
31+
32+
3. **System Administrator rights for environment**
33+
- Required for increasing maximum file size for importing solution with PCF component
34+
35+
4. **Enable Power Apps component framework feature**
36+
- To add code components to an app, you need to enable the Power Apps component framework feature in each environment where you want to use them. See enable [Power Apps component framework for canvas apps](https://learn.microsoft.com/power-apps/developer/component-framework/component-framework-for-canvas-apps#enable-the-power-apps-component-framework-feature)
37+
38+
## Setup Instructions
39+
40+
### Step 1: Configure App Registration
41+
This step requires permissions to create application identities in your Azure tenant. For this sample, create a Native Client Application Identity (no secrets required):
42+
43+
1. **Open Azure Portal**
44+
- Navigate to [portal.azure.com](https://portal.azure.com)
45+
- Go to **Microsoft Entra ID** (Azure AD)
46+
47+
2. **Create a new App Registration**
48+
- Click **App registrations** → **New registration**
49+
- Provide a **Name** (e.g., "Copilot Studio Chat Control")
50+
- Choose **"Accounts in this organization directory only"**
51+
- Under **Permissions** give this application registration Copilot Studio Invoke permissions
52+
- Under **Redirect URI**:
53+
- Select **"Single-page application"** from the platform dropdown
54+
- Add the below redirects for the chat control to work when running the app
55+
1. [https://runtime-app.preview.powerplatform.com/]()
56+
2. [https://runtime-app.powerplatform.com]()
57+
3. [https://runtime-app.powerplatform.com/control]()
58+
4. [https://apps.powerapps.com/]()
59+
5. Instance URL (example format: [https://org1231243.crm.dynamics.com/]()), see Instance URL in [Session details](https://learn.microsoft.com/power-apps/maker/canvas-apps/get-sessionid) or in the environment details in the Power Platform Admin Center.
60+
- Add the below redirects for the chat control to work in the Canvas Apps Designer, you can find the island value in the [Session details](https://learn.microsoft.com/power-apps/maker/canvas-apps/get-sessionid), Cluster URI suffix, the island comes before .gateway.prod.island
61+
1. [https://authoring.**your island**.powerapps.com]()
62+
2. [https://authoring.**your island**.powerapps.com/control]()
63+
64+
Example: [https://authoring.us-il108.gateway.prod.island.powerapps.com]()
65+
66+
- Click **Register**
67+
68+
- Copy **Application (client) ID**, **Directory (tenant) ID** (you will need those values for configuring the chat component)
69+
70+
### Step 2: Get Copilot Studio Configuration
71+
72+
1. Open your Copilot Studio environment
73+
2. Navigate to your published agent
74+
3. Ensure the agent is configured with ['Authenticate with Microsoft'](https://learn.microsoft.com/microsoft-copilot-studio/configuration-end-user-authentication#authenticate-with-microsoft)
75+
4. Collect the required configuration values
76+
**Get Environment ID and Agent Identifier**
77+
- Go to **Settings** → **Advanced** → **Metadata**
78+
- Copy the following values:
79+
- **Environment ID**
80+
- **Schema name** (this is your Agent Identifier, e.g., `cr770_myAgent`)
81+
82+
### Step 3: Increase maximum file size
83+
84+
1. Navigate to https://make.powerapps.com and make sure the proper environment is selected
85+
2. Click the gear icon (top right) and select Advanced Settings
86+
3. Select Email Configuration
87+
4. Select Email Settings
88+
5. On the Email tab, scroll down to **Set file size limit for attachments** and increase the file size limit to 25,000 kb.
89+
6. Click OK
90+
91+
### Step 4: Download and import solution file
92+
93+
1. Download either managed or unmanaged solution file from this Github Repo, see folder Solutions. Preferably download managed solution file.
94+
2. [Import](https://learn.microsoft.com/power-apps/maker/data-platform/import-update-export-solutions) the solution file in the environment
95+
96+
### Step 5: Use the ChatControl in the canvas app
97+
98+
1. In your Power Apps Studio, create a new Canvas App or edit an existing app to which you want to add this Chat component.
99+
2. [Add the chat component to your app](https://learn.microsoft.com/power-apps/developer/component-framework/component-framework-for-canvas-apps#add-components-to-a-canvas-app)
100+
3. Configure the required properties
101+
102+
### Required Properties
103+
104+
The control requires the following configuration properties:
105+
106+
| Property | Type | Description |
107+
|----------|------|-------------|
108+
| `agentTitle` | String | Display title for the agent (defaults to "Agent") |
109+
| `appClientId` | String | Application (client) ID |
110+
| `tenantId` | String | Directory (tenant) ID |
111+
| `environmentId` | String | Power Platform environment ID |
112+
| `agentIdentifier` | String | Copilot Studio agent schema name |
113+
| `username` | String | Current user's email (defaults to `User().Email`) |
114+
115+
116+
### Optional Properties
117+
118+
| Property | Type | Description |
119+
|----------|------|-------------|
120+
| `message` | String | Message to send to the agent |
121+
| `eventValue` | String | Custom event value to send on conversation start |
122+
| `disableFileUpload` | Boolean | Disable file upload functionality |
123+
| `styleOptions` | String | JSON string for WebChat style customization |
124+
125+
### Output Properties
126+
127+
| Property | Type | Description |
128+
|----------|------|-------------|
129+
| `response` | String | Latest response message from the agent |
130+
| `conversationId` | String | Current conversation ID |
131+
132+
133+
### Project Structure
134+
135+
```
136+
ChatControl/
137+
├── ChatControl/
138+
│ ├── Chat/
139+
│ │ ├── Chat.tsx # Main chat component
140+
│ │ └── acquireToken.ts # MSAL authentication logic
141+
│ ├── generated/ # Auto-generated manifest types
142+
│ ├── index.ts # PCF control implementation
143+
│ └── ControlManifest.Input.xml # Control manifest definition
144+
├── package.json # Project dependencies and scripts
145+
└── README.md # This file
146+
```
147+
148+
## Usage Example
149+
150+
### Style Options
151+
152+
The `styleOptions` property accepts a JSON string following the Bot Framework WebChat style options schema:
153+
154+
```json
155+
{
156+
"bubbleBackground": "#ffffff",
157+
"bubbleFromUserBackground": "#0078d4",
158+
"bubbleFromUserTextColor": "#ffffff",
159+
"bubbleTextColor": "#000000",
160+
"rootHeight": "100%",
161+
"rootWidth": "100%"
162+
}
163+
```
164+
The [Webchat Playground](https://learn.microsoft.com/microsoft-copilot-studio/guidance/kit-webchat-playground) from the [Copilot Studio Kit](https://learn.microsoft.com/microsoft-copilot-studio/guidance/kit-overview) helps you customize the appearance and behavior of your copilot agent Web Chat. The intuitive user interface lets you modify colors, fonts, thumbnails, and more to match your brand's identity.
165+
166+
## Troubleshooting
167+
168+
### "Unable to acquire token" error
169+
170+
If you encounter this error:
171+
1. Open your browser's Developer Tools (F12)
172+
2. Go to the **Network** tab
173+
3. Look for failed authentication requests (usually to `login.microsoftonline.com`)
174+
4. Click on the failed requests to see detailed error messages
175+
5. Follow the authentication URLs that MSAL is attempting - the actual error details are often revealed in the response or redirect parameters
176+
177+
## License
178+
179+
This project is licensed under the MIT License - see the LICENSE file for details.
180+
181+
182+
## Additional Resources
183+
184+
- [Power Apps Component Framework Documentation](https://docs.microsoft.com/powerapps/developer/component-framework/overview)
185+
- [Bot Framework WebChat Documentation](https://github.com/microsoft/BotFramework-WebChat)
186+
- [Microsoft Copilot Studio Documentation](https://docs.microsoft.com/power-virtual-agents/)
187+
- [MSAL.js Documentation](https://docs.microsoft.com/azure/active-directory/develop/msal-overview)

‎PCFControls/ChatControl/Solutions/AgentControls_1_0_0_9.zip‎

2.63 MB
Binary file not shown.

‎PCFControls/ChatControl/Solutions/AgentControls_1_0_0_9_managed.zip‎

2.63 MB
Binary file not shown.

‎PCFControls/ChatControl/Source/ChatControl.pcfproj‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<Project ToolsVersion="15.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
3+
<PropertyGroup>
4+
<PowerAppsTargetsPath>$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v$(VisualStudioVersion)\PowerApps</PowerAppsTargetsPath>
5+
</PropertyGroup>
6+
7+
<Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" />
8+
<Import Project="$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.props" Condition="Exists('$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.props')" />
9+
10+
<PropertyGroup>
11+
<Name>ChatControl</Name>
12+
<ProjectGuid>c19dce7b-fa78-4301-84cc-4e217d9b5ad2</ProjectGuid>
13+
<OutputPath>$(MSBuildThisFileDirectory)out\controls</OutputPath>
14+
</PropertyGroup>
15+
16+
<PropertyGroup>
17+
<TargetFrameworkVersion>v4.6.2</TargetFrameworkVersion>
18+
<!--Remove TargetFramework when this is available in 16.1-->
19+
<TargetFramework>net462</TargetFramework>
20+
<RestoreProjectStyle>PackageReference</RestoreProjectStyle>
21+
</PropertyGroup>
22+
23+
<ItemGroup>
24+
<PackageReference Include="Microsoft.PowerApps.MSBuild.Pcf" Version="1.*" />
25+
<PackageReference Include="Microsoft.NETFramework.ReferenceAssemblies" Version="1.0.0" PrivateAssets="All" />
26+
</ItemGroup>
27+
28+
<ItemGroup>
29+
<ExcludeDirectories Include="$(MSBuildThisFileDirectory)\.gitignore" />
30+
<ExcludeDirectories Include="$(MSBuildThisFileDirectory)\bin\**" />
31+
<ExcludeDirectories Include="$(MSBuildThisFileDirectory)\obj\**" />
32+
<ExcludeDirectories Include="$(OutputPath)\**" />
33+
<ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.pcfproj" />
34+
<ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.pcfproj.user" />
35+
<ExcludeDirectories Include="$(MSBuildThisFileDirectory)\*.sln" />
36+
<ExcludeDirectories Include="$(MSBuildThisFileDirectory)\node_modules\**" />
37+
</ItemGroup>
38+
39+
<ItemGroup>
40+
<None Include="$(MSBuildThisFileDirectory)\**" Exclude="@(ExcludeDirectories)" />
41+
</ItemGroup>
42+
43+
<Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets" />
44+
<Import Project="$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.targets" Condition="Exists('$(PowerAppsTargetsPath)\Microsoft.PowerApps.VisualStudio.Pcf.targets')" />
45+
46+
</Project>

0 commit comments

Comments
 (0)