Introduction
Microsoft Teams est bien plus qu'un outil de collaboration : sa plateforme de développement permet de créer des bots avancés qui s'intègrent nativement pour automatiser les workflows, envoyer des notifications proactives ou interfacer avec Microsoft Graph. En 2026, avec l'essor de l'IA et des apps hybrides, maîtriser le Bot Framework SDK est essentiel pour les développeurs seniors.
Ce tutoriel avancé vous guide pas à pas pour construire un bot complet : gestion d'adaptive cards interactives, authentification OAuth2 via Azure AD, appels à Graph API pour récupérer les infos utilisateur, et messages proactifs. Imaginez un bot qui notifie les tâches urgentes d'un Planner directement dans un canal Teams, avec un task module pour édition inline.
Pourquoi c'est crucial ? 80% des entreprises utilisent Teams ; un bot custom booste la productivité de 30% selon Microsoft. Ce guide délivre du code 100% fonctionnel, prêt à déployer sur Azure. Durée estimée : 2h pour un dev expérimenté.
Prérequis
- Compte Azure gratuit (pour Bot Service et App Registration)
- Node.js 20+ et npm/yarn
- Compte Microsoft 365 Developer (gratuit via aka.ms/teamsdev)
- VS Code avec extensions Bot Framework et Teams Toolkit
- Connaissances avancées en TypeScript, async/await et REST APIs
- Clés API Graph (permissions : User.Read, ChannelMessage.Send)
Initialiser le projet Bot Framework
npx @microsoft/teamsapp@latest create --type bot
cd teams-bot
npm install
npm install @azure/msal-node @microsoft/microsoft-graph-client
npm install adaptivecards
npm run devCette commande utilise Teams Toolkit CLI pour scaffold un projet bot prêt pour Teams. Elle installe les dépendances essentielles : MSAL pour l'auth AAD et Graph Client pour les appels API avancés. Évitez les anciennes versions de yo botbuilder ; Teams Toolkit est optimisé pour 2026 avec support natif des apps manifest v3.
Configurer l'Azure Bot Service
Créez un Bot Channels Registration dans le portail Azure :
- Portail Azure > Bot Services > Nouveau bot
- Associez à Teams channel
- Notez l'App ID et le secret pour .env
Générez un App Registration pour l'auth OAuth :
- Azure AD > App registrations > Nouvelle
- Redirect URI :
https://token.botframework.com/.auth/web/redirect - Permissions Graph : Delegated (User.Read, Channel.ReadBasic.All)
Copiez
MICROSOFT_APP_ID et MICROSOFT_APP_PASSWORD dans .env.Implémenter le bot de base avec dialogs
import {
Application,
DefaultAzureCredential,
TeamsActivityHandler,
MessageFactory,
CardFactory,
TurnContext,
teamsGetChannelId
} from 'botbuilder';
import { MicrosoftGraphClient } from '@microsoft/microsoft-graph-client';
import * as msal from '@azure/msal-node';
import * as dotenv from 'dotenv';
dotenv.config();
const appId = process.env.MicrosoftAppId!;
const appPassword = process.env.MicrosoftAppPassword!;
class TeamsBot extends TeamsActivityHandler {
constructor() {
super();
this.onMessage(async (context, next) => {
const channelId = teamsGetChannelId(context.activity);
await context.sendActivity(MessageFactory.text(`Salut dans le canal ${channelId}! Tape 'graph' pour tester Graph API.`));
await next();
});
this.onMembersAdded(async (context, next) => {
await context.sendActivity(MessageFactory.text('Bot avancé Teams prêt!'));
await next();
});
}
async getGraphClient(context: TurnContext) {
const tokenResponse = await this.getToken(context);
const graphClient = MicrosoftGraphClient.init({
authProvider: {
getAccessToken: () => Promise.resolve(tokenResponse.token)
}
});
return graphClient;
}
}
export default {
async run() {
const app = new Application({
credential: new DefaultAzureCredential(),
endpoints: { messagingEndpoint: process.env.MessagingEndpoint! },
});
app.addHandler(new TeamsBot());
const port = process.env.port || process.env.PORT || 3978;
app.listen(port, () => {
console.log(`Bot listening on ${port}`);
});
}
};Ce code squelette étend TeamsActivityHandler pour gérer messages et ajouts de membres. Il prépare l'intégration Graph via un helper getGraphClient. Utilisez DefaultAzureCredential pour prod ; en dev, fallback sur App ID/Password. Piège : Oubliez pas d'exposer MessagingEndpoint dans Azure Bot.
Ajouter adaptive cards interactives
import { CardFactory, ActionTypes, CardAction, Attachment } from 'botbuilder';
export function createTaskCard(taskName: string): Attachment {
return CardFactory.adaptiveCard({
type: 'AdaptiveCard',
version: '1.5',
body: [
{
type: 'TextBlock',
text: `Tâche urgente: **${taskName}**`,
weight: 'Bolder',
size: 'Large'
},
{
type: 'Input.Text',
id: 'comment',
placeholder: 'Ajoutez un commentaire'
}
],
actions: [
{
type: 'Action.Submit',
title: 'Valider',
data: { action: 'submitTask' }
},
{
type: 'Action.ShowCard',
title: 'Détails',
card: {
type: 'AdaptiveCard',
body: [{ type: 'TextBlock', text: 'Détails avancés...' }]
}
}
]
});
}Cette fonction génère une Adaptive Card v1.5 avec inputs et actions imbriquées (ShowCard pour task module-like). Soumettez via onSubmitAction pour processing. Avantage : Riche UI native Teams. Piège : Validez toujours les données soumises côté bot pour sécurité.
Gérer les actions de cards et Graph API
Intégrez dans le bot :
``typescriptTâche validée par ${user.displayName}
this.onAdaptiveCardAction(async (context, action, next) => {
if (action.data.action === 'submitTask') {
const graphClient = await this.getGraphClient(context);
const user = await graphClient.api('/me').get();
await context.sendActivity();`
}
await next();
});
Pour messages proactifs : Stockez conversationReference et utilisez adapter.continueConversation`.
Manifeste d'app Teams complet
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
"manifestVersion": "1.16",
"version": "1.0.0",
"id": "com.example.teamsbot",
"packageName": "com.example.teamsbot",
"developer": {
"name": "Learni Dev",
"websiteUrl": "https://learni-group.com",
"privacyUrl": "https://privacy.example.com",
"termsOfUseUrl": "https://terms.example.com"
},
"icons": {
"color": "color.png",
"outline": "outline.png"
},
"name": {
"short": "Bot Avancé Teams",
"full": "Bot personnalisé avec Graph et Cards"
},
"description": {
"short": "Bot avancé",
"full": "Gère tâches et Graph API"
},
"accentColor": "#FFFFFF",
"bots": [
{
"botId": "YOUR_APP_ID",
"scopes": ["personal", "team", "groupchat"],
"supportsFiles": false,
"isNotificationOnly": false,
"supportsCalling": false,
"supportsVideo": false
}
],
"permissions": ["identity", "messageTeamMembers"],
"validDomains": ["token.botframework.com", "graph.microsoft.com"]
}Manifest v1.16 pour bots multi-scope (personal/team). Remplacez YOUR_APP_ID par votre Azure App ID. ValideDomains critique pour OAuth et Graph. Sideload via Teams Developer Portal > Apps > Manage apps > Upload.
Authentification OAuth2 et token Graph
import { TurnContext } from 'botbuilder';
import { Client } from '@azure/msal-node';
const msalConfig = {
auth: {
clientId: process.env.MicrosoftAppId!,
authority: 'https://login.microsoftonline.com/common',
clientSecret: process.env.MicrosoftAppPassword!
}
};
const cca = new Client(msalConfig);
export async function getToken(context: TurnContext): Promise<any> {
const conversationRef = TurnContext.getConversationReference(context.activity);
const ticket = await context.adapter.getUserToken(context, 'YOUR_MAGIC_CODE');
if (ticket) {
return ticket;
}
await context.adapter.signOutUser(context, 'YOUR_MAGIC_CODE', '/.auth/web/redirect');
return null;
}Intègre MSAL Node pour OAuth2 fluide dans Teams. Utilisez getUserToken pour delegated tokens Graph. Magic code : Chaîne unique par bot. Piège : Gérez signOut pour refresh ; testez en prod car dev portal simule mal l'auth.
Déploiement sur Azure avec CI/CD
npm run build
git init
git add .
git commit -m "Initial bot"
# Azure CLI
az login
az bots registration create --name MyTeamsBot --resource-group MyRG --sku S1 --microsoft-app-id $MicrosoftAppId --microsoft-app-password $MicrosoftAppPassword --endpoint $MessagingEndpoint
# Deploy via Teams Toolkit
npx @microsoft/teamsapp@latest provision
npx @microsoft/teamsapp@latest deploy
# Ou Azure App Service
az webapp up --name myteamsbot --resource-group MyRG --runtime "NODE|20-lts"Script complet pour provisionner Bot Service et déployer. Utilisez SKU S1 pour prod (proactive messaging). Teams Toolkit automatise le manifest ZIP. Piège : Endpoint doit être HTTPS ; configurez slots de déploiement pour zero-downtime.
Bonnes pratiques
- Toujours async/await : Évitez les callbacks pour la lisibilité et les erreurs Graph.
- Rate limiting Graph : Implémentez retry avec exponential backoff (ms-rest-js).
- Sécurité : Validez tous les inputs cards ; utilisez least-privilege permissions AAD.
- Proactive messaging : Stockez refs en Cosmos DB pour scalabilité.
- Monitoring : Intégrez Application Insights dès le setup pour traces et métriques.
Erreurs courantes à éviter
- CORS/Endpoint non-HTTPS : Azure refuse les bots insecure ; forcez ngrok pour dev.
- Permissions Graph manquantes : Vérifiez Admin Consent dans AAD ; testez via Graph Explorer.
- ConversationReference périmée : Refresh toutes les 24h pour proactifs.
- Adaptive Cards v1.5 non-supportée : Downgrade à v1.4 si legacy clients.
Pour aller plus loin
- Docs officielles : Bot Framework et Teams Samples
- Avancé : Intégrez Copilot Studio pour low-code + custom skills
- Formations : Découvrez nos formations Microsoft 365 Learni pour certification PL-900/PL-200.
- Repo GitHub exemple : Forkez ce tuto sur github.com/learni-dev/teams-bot-2026.