Implementing Barcode Scanning in Microsoft Teams Apps

If you are building a Microsoft Teams app and want to integrate barcode or QR code scanning, the setup process is quite straightforward. However, there is a crucial API caveat developers need to be aware of when choosing between the newer and legacy scanning functions.

While Microsoft has introduced newer API surfaces for this feature, these don’t seem ready for real-world application. Here is a pragmatic approach to ensure a reliable implementation in production.

1. Manifest Requirements

To enable the camera, you must first include the media device permission in your Teams app manifest. Add the following to your manifest.json:

"devicePermissions": [
  "media"
]

2. The Current State of Barcode APIs

There is an ongoing misconception that a separate barcode permission exists. However, the official documentation strictly requires the media permission to access the camera for scanning.

Furthermore, while the TeamsJS SDK introduced the newer microsoftTeams.barCode.scanBarCode() API, it remains highly unreliable. Developers actively report receiving a NOT_SUPPORTED_ON_PLATFORM (Error 100) on supported mobile devices (see GitHub issue #2870). Because of these persisting issues, the developer community continues to rely on the legacy microsoftTeams.media.scanBarCode(...) function as the production-ready standard.

3. Platform Limitations

It is important to understand the current platform reality for this feature:

• Barcode and QR scanning is fully supported on Teams mobile clients (iOS and Android).
• Desktop and web contexts typically return a NOT_SUPPORTED_ON_PLATFORM error.

Always verify support at runtime and ensure your code handles these errors gracefully on unsupported clients.

4. Robust Implementation Pattern

To ensure a smooth user experience, a robust implementation must verify runtime support and gracefully handle the various error codes returned by the SDK. For example, Outlook mobile currently lacks scanner support, so we must explicitly check the host name. Additionally, mapping the numeric SDK error codes (such as handling user cancellations without throwing errors) is essential.

Below is a reliable TypeScript snippet demonstrating how to accurately check for support and safely invoke the scanner:

import * as microsoftTeams from "@microsoft/teams-js";

// 1. Verify Support
const context = await microsoftTeams.app.getContext().catch(() => undefined);
const hostName = String(context?.app?.host?.name ?? '').toLowerCase();
const canScan = !hostName.includes('outlook') && typeof microsoftTeams.media?.scanBarCode === 'function';

if (!canScan) {
  console.error("Barcode scanning is not supported on this platform.");
  return;
}

// 2. Invoke Scanner
microsoftTeams.media.scanBarCode((error, decodedText) => {
  if (error) {
    switch (error.errorCode) {
      case 100: console.error('Platform not supported'); break;
      case 500: console.error('Internal error occurred'); break;
      case 1000: console.error('Permission denied to access camera'); break;
      case 3000: console.error('Device does not support barcode scanning'); break;
      case 4000: console.error('Invalid arguments provided'); break;
      case 8000: return; // User cancelled, no error needed
      case 8001: console.error('Barcode scanning timed out'); break;
      case 9000: console.error('Platform is outdated'); break;
      default: console.error('Unknown error:', error.message);
    }
  } else if (decodedText) {
    console.log("Scanned value:", decodedText);
  }
}, { timeOutIntervalInSec: 30 });