Skip to content

Commit 3d75a6a

Browse files
Copilotrido-min
Copilot
and
rido-min
committed
Add README for MessageExtensions sample with Teams manifest setup instructions
Co-authored-by: rido-min <[email protected]>
1 parent 5182bb1 commit 3d75a6a

File tree

1 file changed

+399
-0
lines changed

1 file changed

+399
-0
lines changed

‎Samples/Samples.MessageExtensions/README.md‎

Lines changed: 399 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,399 @@
1+
# Message Extensions Sample
2+
3+
This sample demonstrates how to implement message extensions (also known as messaging extensions) in Microsoft Teams using the Teams AI SDK for .NET. Message extensions allow users to interact with your bot directly from the compose area or from search in Teams.
4+
5+
## Features
6+
7+
This sample includes comprehensive message extension functionality:
8+
9+
- **Search-based message extensions** - Query and return results
10+
- **Action-based message extensions** - Create cards from user input
11+
- **Link unfurling** - Automatically unfurl links in conversations
12+
- **Settings configuration** - Configure message extension settings
13+
- **Task modules** - Display interactive forms
14+
- **Message actions** - Get details from existing messages
15+
16+
## Prerequisites
17+
18+
- .NET 9.0 or later
19+
- Azure Bot Service registration
20+
- Dev tunnels or ngrok for local development
21+
- Microsoft Teams (desktop or web client)
22+
- Microsoft 365 tenant with Teams enabled
23+
24+
## Project Structure
25+
26+
```
27+
Samples.MessageExtensions/
28+
├── Program.cs # Main bot logic and message extension handlers
29+
├── Samples.MessageExtensions.csproj # Project file with SDK dependencies
30+
├── appsettings.json # Bot credentials configuration
31+
├── Properties/launchSettings.json # Launch configuration (port 3978)
32+
└── README.md # This file
33+
```
34+
35+
## Setup
36+
37+
### 1. Azure Bot Registration
38+
39+
1. Navigate to the [Azure Portal](https://portal.azure.com)
40+
2. Create an **Azure Bot** resource:
41+
- Click "Create a resource"
42+
- Search for "Azure Bot"
43+
- Click "Create"
44+
3. Configure the bot:
45+
- **Bot handle**: Choose a unique name
46+
- **Subscription**: Select your subscription
47+
- **Resource group**: Create new or select existing
48+
- **Pricing tier**: Choose appropriate tier (F0 for free)
49+
- **Microsoft App ID**: Create new Microsoft App ID
50+
4. After creation, go to **Configuration**:
51+
- Note the **Microsoft App ID** (Client ID)
52+
- Click "Manage" next to Microsoft App ID
53+
- In the app registration, create a new **Client Secret** under "Certificates & secrets"
54+
- Copy the secret value immediately (it won't be shown again)
55+
5. Set the **Messaging endpoint**: `https://your-tunnel-url/api/messages` (update after setting up dev tunnel)
56+
57+
### 2. Update Configuration
58+
59+
Update `appsettings.json` with your bot credentials:
60+
61+
```json
62+
{
63+
"Teams": {
64+
"ClientId": "your-microsoft-app-id",
65+
"ClientSecret": "your-client-secret"
66+
}
67+
}
68+
```
69+
70+
### 3. Local Development Setup
71+
72+
#### Option A: Using Dev Tunnels (Recommended)
73+
74+
1. Install dev tunnels:
75+
```bash
76+
winget install Microsoft.DevTunnels
77+
```
78+
79+
2. Login to dev tunnels:
80+
```bash
81+
devtunnel user login
82+
```
83+
84+
3. Create a tunnel:
85+
```bash
86+
devtunnel create --allow-anonymous
87+
```
88+
89+
4. Start the tunnel (port 3978):
90+
```bash
91+
devtunnel port create -p 3978
92+
devtunnel host
93+
```
94+
95+
5. Copy the tunnel URL (e.g., `https://abc123.devtunnels.ms`)
96+
97+
#### Option B: Using ngrok
98+
99+
1. Download and install [ngrok](https://ngrok.com/download)
100+
101+
2. Start ngrok tunnel:
102+
```bash
103+
ngrok http 3978
104+
```
105+
106+
3. Copy the HTTPS forwarding URL (e.g., `https://abc123.ngrok.io`)
107+
108+
### 4. Update Azure Bot Messaging Endpoint
109+
110+
1. Go back to your Azure Bot resource in the Azure Portal
111+
2. Navigate to **Configuration**
112+
3. Update **Messaging endpoint** to: `https://your-tunnel-url/api/messages`
113+
4. Click **Apply**
114+
115+
### 5. Configure Teams App Manifest
116+
117+
Create a Teams app manifest to register your message extension. Create a folder called `AppPackage` with the following files:
118+
119+
#### manifest.json
120+
121+
```json
122+
{
123+
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
124+
"manifestVersion": "1.17",
125+
"version": "1.0.0",
126+
"id": "YOUR-APP-ID-GUID",
127+
"packageName": "com.example.messageextensions",
128+
"developer": {
129+
"name": "Your Company",
130+
"websiteUrl": "https://example.com",
131+
"privacyUrl": "https://example.com/privacy",
132+
"termsOfUseUrl": "https://example.com/terms"
133+
},
134+
"name": {
135+
"short": "Message Extensions Sample",
136+
"full": "Message Extensions Sample for Teams"
137+
},
138+
"description": {
139+
"short": "Sample message extensions bot",
140+
"full": "A comprehensive sample demonstrating message extensions functionality in Microsoft Teams"
141+
},
142+
"icons": {
143+
"outline": "outline.png",
144+
"color": "color.png"
145+
},
146+
"accentColor": "#FFFFFF",
147+
"bots": [
148+
{
149+
"botId": "YOUR-MICROSOFT-APP-ID",
150+
"scopes": [
151+
"personal",
152+
"team",
153+
"groupchat"
154+
],
155+
"supportsFiles": false,
156+
"isNotificationOnly": false
157+
}
158+
],
159+
"composeExtensions": [
160+
{
161+
"botId": "YOUR-MICROSOFT-APP-ID",
162+
"commands": [
163+
{
164+
"id": "searchQuery",
165+
"type": "query",
166+
"title": "Search",
167+
"description": "Search for items",
168+
"initialRun": false,
169+
"parameters": [
170+
{
171+
"name": "searchQuery",
172+
"title": "Search",
173+
"description": "Enter search terms",
174+
"inputType": "text"
175+
}
176+
]
177+
},
178+
{
179+
"id": "createCard",
180+
"type": "action",
181+
"title": "Create Card",
182+
"description": "Create a custom card",
183+
"context": ["compose", "commandBox"],
184+
"parameters": [
185+
{
186+
"name": "title",
187+
"title": "Title",
188+
"description": "Card title",
189+
"inputType": "text"
190+
},
191+
{
192+
"name": "description",
193+
"title": "Description",
194+
"description": "Card description",
195+
"inputType": "textarea"
196+
}
197+
]
198+
},
199+
{
200+
"id": "getMessageDetails",
201+
"type": "action",
202+
"title": "Get Message Details",
203+
"description": "Get details from a message",
204+
"context": ["message"]
205+
}
206+
],
207+
"messageHandlers": [
208+
{
209+
"type": "link",
210+
"value": {
211+
"domains": [
212+
"*.example.com"
213+
]
214+
}
215+
}
216+
]
217+
}
218+
],
219+
"permissions": [
220+
"identity",
221+
"messageTeamMembers"
222+
],
223+
"validDomains": [
224+
"*.botframework.com",
225+
"YOUR-TUNNEL-DOMAIN"
226+
]
227+
}
228+
```
229+
230+
#### Icon Requirements
231+
232+
You'll need two icon files in the same folder:
233+
234+
- **color.png**: 192x192 pixels, full color icon
235+
- **outline.png**: 32x32 pixels, transparent outline icon
236+
237+
You can create simple icons or use placeholder images for testing.
238+
239+
#### Creating the App Package
240+
241+
1. Create icons (or download sample icons)
242+
2. Update the manifest:
243+
- Replace `YOUR-APP-ID-GUID` with a new GUID (you can generate one at [guidgen.com](https://www.guidgen.com/))
244+
- Replace `YOUR-MICROSOFT-APP-ID` with your Azure Bot's Microsoft App ID (same as ClientId)
245+
- Replace `YOUR-TUNNEL-DOMAIN` with your tunnel domain (e.g., `abc123.devtunnels.ms`)
246+
- Update company and URL information
247+
3. Zip the three files (manifest.json, color.png, outline.png) into a package named `MessageExtensions.zip`
248+
249+
### 6. Install the App in Teams
250+
251+
1. Open Microsoft Teams
252+
2. Click on **Apps** in the left sidebar
253+
3. Click **Manage your apps** (bottom left)
254+
4. Click **Upload an app** → **Upload a custom app**
255+
5. Select your `MessageExtensions.zip` file
256+
6. Click **Add** to install the app
257+
258+
## Running the Sample
259+
260+
```bash
261+
# Navigate to the project directory
262+
cd Samples/Samples.MessageExtensions
263+
264+
# Run the bot
265+
dotnet run
266+
```
267+
268+
The bot will start on `http://localhost:3978` by default.
269+
270+
## Using the Message Extension
271+
272+
### Search Command
273+
274+
1. In any chat or channel in Teams, click the **+** icon in the compose area
275+
2. Find and select your **Message Extensions Sample** app
276+
3. Type a search query in the search box
277+
4. The bot will return 5 adaptive card results based on your query
278+
5. Click on a result to insert it into the conversation
279+
280+
### Create Card Action
281+
282+
1. Click the **...** (more options) button in the compose area
283+
2. Select **Message Extensions Sample**
284+
3. Choose **Create Card**
285+
4. Fill in the title and description
286+
5. Submit to create and insert the card
287+
288+
### Get Message Details (Message Action)
289+
290+
1. Hover over any message in a conversation
291+
2. Click the **...** (more actions) menu
292+
3. Select **More actions** → **Get Message Details**
293+
4. The bot will display the message details in a card
294+
295+
### Link Unfurling
296+
297+
1. Configure the domains you want to unfurl in the manifest
298+
2. Paste a link from those domains in a conversation
299+
3. The bot will automatically unfurl it with a rich preview card
300+
301+
## Message Extension Handlers
302+
303+
The sample implements the following handlers:
304+
305+
- **`[MessageExtension.Query]`** (Line 70) - Handles search queries
306+
- **`[MessageExtension.SubmitAction]`** (Line 99) - Handles action submissions (create card, message actions)
307+
- **`[MessageExtension.QueryLink]`** (Line 127) - Handles link unfurling
308+
- **`[MessageExtension.SelectItem]`** (Line 146) - Handles item selection from search results
309+
- **`[MessageExtension.QuerySettingsUrl]`** (Line 160) - Returns settings configuration URL
310+
- **`[MessageExtension.FetchTask]`** (Line 178) - Returns task module for actions
311+
- **`[MessageExtension.Setting]`** (Line 191) - Handles settings updates
312+
313+
## Key Features Demonstrated
314+
315+
### AttachmentLayout Types
316+
317+
The sample uses the new `MessageExtensions.AttachmentLayout` type which supports:
318+
319+
```csharp
320+
// List layout (default)
321+
AttachmentLayout = MessageExtensions.AttachmentLayout.List
322+
323+
// Grid layout (new in this version)
324+
AttachmentLayout = MessageExtensions.AttachmentLayout.Grid
325+
```
326+
327+
### Adaptive Cards
328+
329+
Search results return adaptive cards with:
330+
- Title and description
331+
- Preview cards for search results
332+
- Interactive elements
333+
334+
### Task Modules
335+
336+
Action-based commands display task modules for data collection.
337+
338+
### Error Handling
339+
340+
Comprehensive error handling with user-friendly error messages.
341+
342+
## Dependencies
343+
344+
The project references the following Teams AI SDK libraries:
345+
346+
- `Microsoft.Teams.Apps` - Core Teams bot functionality
347+
- `Microsoft.Teams.Api` - Teams API models and clients
348+
- `Microsoft.Teams.Common` - Common utilities and logging
349+
- `Microsoft.Teams.Cards` - Adaptive Cards support
350+
- `Microsoft.Teams.Extensions.Hosting` - ASP.NET Core integration
351+
- `Microsoft.Teams.Plugins.AspNetCore` - ASP.NET Core plugin support
352+
- `Microsoft.Teams.Plugins.AspNetCore.DevTools` - Development tools
353+
354+
## Troubleshooting
355+
356+
### Bot Not Responding
357+
358+
- Verify the messaging endpoint in Azure Bot is correct and includes `https://`
359+
- Ensure dev tunnel or ngrok is running
360+
- Check that the bot is running locally (`dotnet run`)
361+
- Review console logs for errors
362+
363+
### Message Extension Not Appearing
364+
365+
- Verify the manifest is correctly configured
366+
- Check that `botId` in `composeExtensions` matches your Microsoft App ID
367+
- Ensure the app is installed in Teams
368+
- Try reinstalling the app package
369+
370+
### Authentication Errors
371+
372+
- Verify `ClientId` and `ClientSecret` in `appsettings.json` are correct
373+
- Ensure the Client Secret hasn't expired
374+
- Check Azure Bot configuration
375+
376+
### Commands Not Working
377+
378+
- Review the `commandId` values in the manifest match those in the code
379+
- Check console logs for handler execution
380+
- Verify the command types (`query` vs `action`) are correct
381+
382+
### Settings Not Loading
383+
384+
- Ensure the settings page HTML is being served correctly
385+
- Verify the `/settings` endpoint is accessible
386+
- Check browser console for errors
387+
388+
## Additional Resources
389+
390+
- [Microsoft Teams Message Extensions Documentation](https://learn.microsoft.com/microsoftteams/platform/messaging-extensions/what-are-messaging-extensions)
391+
- [Teams App Manifest Schema](https://learn.microsoft.com/microsoftteams/platform/resources/schema/manifest-schema)
392+
- [Adaptive Cards Designer](https://adaptivecards.io/designer/)
393+
- [Teams AI SDK Documentation](https://microsoft.github.io/teams-ai)
394+
395+
## Support
396+
397+
For issues and questions:
398+
- Check the [Teams AI SDK GitHub repository](https://github.com/microsoft/teams-ai)
399+
- Review [Microsoft Teams Platform documentation](https://learn.microsoft.com/microsoftteams/platform/)

0 commit comments

Comments
 (0)