[Doc Feature][PSTN-Calling-Extensibility][4045801]

.vscode/settings.json

@@ -24,6 +24,7 @@
         "officedev",
         "outgoingwebhook",
         "preauthorizedapplications",
+        "PSTN",
         "redirections",
         "requiredresourceaccess",
         "Restify",

msteams-platform/TOC.yml

@@ -33,7 +33,6 @@
     href: get-started/build-message-extension.md
   - name: Tool options and code samples
     href: get-started/tool-options-and-code-samples.md
-
 - name: Plan your app
   items:
   - name: Overview
@@ -568,11 +567,14 @@
   - name: Overview
     href: apps-in-teams-meetings/teams-apps-in-meetings.md
     displayName: apps in meetings, meeting lifecycle, meeting types in Teams, guest user, in-tenant user, federated or external user, anonymous user, scenes for meetings, meeting participants, app caching in Teams meeting
-  - name: Enable and configure apps for Teams meetings
+  - name: Enable and configure apps for Teams meetings and calls
     items:
     - name: Build tabs for meeting
       href: apps-in-teams-meetings/build-tabs-for-meeting.md
       displayName: anonymous
+    - name: Build tabs for calling
+      href: apps-in-teams-meetings/build-tabs-for-calling.md
+      displayName: PSTN, calling extensibility, calls in Teams
     - name: Build apps for meeting stage
       href: apps-in-teams-meetings/build-apps-for-teams-meeting-stage.md
       displayName: MicrosoftTeams.meeting.getAppContentStageSharingState

msteams-platform/apps-in-teams-meetings/build-tabs-for-calling.md

@@ -0,0 +1,140 @@
+---
+title: Create Tab Apps for Calling
+author: surbhigupta
+description: Learn to build a tab for initiating one-to-one calls from within Teams
+ms.topic: conceptual
+ms.author: surbhigupta
+ms.localizationpriority: high
+ms.date: 12/02/2024
+---
+
+# Build tabs for calling
+
+> [!NOTE]
+> Calling extensibility is available only for one-on-one chats and in [public developer preview for Teams](../resources/dev-preview/developer-preview-intro.md).
+
+You can now create personal scope apps that integrate seamlessly with Public Switched Telephone Network (PSTN) and Teams-to-Teams calls. By using the right scope and context, you can build apps that utilize tab type, static scope, personal context, and meeting side panels effectively.
+
+This integration is simple. You can create a new personal tab app or update an existing tab app with personal scope and the appropriate context. Apps can access caller ID for specific callers and display relevant information, such as their active cases or billing issues. This enhances the app's utility and provides a richer experience for users during calls.
+
+## Prerequisites
+
+Ensure the following requirements are in place before you create or update a tab app for supporting one-to-one calls:
+
+* **RSC Permissions needed**: Ensure the following [RSC permissions](/microsoftteams/platform/graph-api/rsc/resource-specific-consent) are granted for the app:
+
+  * `OnlineMeetingParticipant.Read.Chat`
+  * `OnlineMeeting.ReadBasic.Chat`
+
+* **Teams JS SDK required**: [TeamsJS SDK Release latest version](https://github.com/OfficeDev/microsoft-teams-library-js/releases/tag/v2.29.0)
+
+* **Caller ID information**: The tab app must utilize the `getMeetingDetailsVerbose` instead of `getMeetingDetails` to get the call related information. The app can get caller ID details such as phone number and email ID.
+
+  For more information, see [get meeting details API](meeting-apps-apis.md#get-meeting-details-api).
+
+## Enable personal tab apps for calling
+
+To enable personal tab app for one-to-one calls:
+
+* [Update app manifest](#update-app-manifest)
+* [Pin your personal tab app to enable calling](#pin-your-personal-tab-app-to-enable-calling)
+
+### Update app manifest
+
+Teams uses the meeting side panel context for adding calling context in the manifest schema.
+Update your [app manifest](/microsoftteams/platform/resources/schema/manifest-schema#statictabs) with the relevant scope and context arrays under the `staticTabs` section. To configure your  personal tab app for one-on-one calls, update the `staticTabs` section as follows:
+
+1. Set the `scope` as `personal` to make your app available in a personal scope and enables the app to make a call.
+1. Set the `context` as `meetingSidePanel` to enable the tab app to be supported
+
+    Here's an example of the update in the `staticTabs` section of app manifest:
+
+    ```Manifest
+
+    "staticTabs":[
+    {
+        "entityId": "contoso",
+        "scopes": ["personal"],
+        "context":[
+            "meetingSidePanel",
+        ],
+        "name": "Contoso"
+        "contentUrl": "http://contoso.com/content",
+        "websiteUrl": "http://contoso.com/content"
+    }
+    ],
+    ```
+
+Here's an example of the app manifest file:
+
+<details>
+<summary>Select to view a sample app manifest.</summary>
+
+```Manifest
+{
+  "$schema": "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json",
+  "version": "1.1.5", 
+  "manifestVersion": "devPreview",
+  "id": "25407c29-8335-68a3-bfdb-4384580a1858",
+  "packageName": "",
+  "name": { "short": "Packing List - PersMSP", "full": "Packing List - PersonalAndMeetingSidePanel" },
+  "developer": {
+    "name": "Microsoft Corporation",
+    "websiteUrl": "https://www.microsoft.com",
+    "privacyUrl": "https://packing-list.azurewebsites.net/privacy.html",
+    "termsOfUseUrl": "https://packing-list.azurewebsites.net/tou.html"
+  },
+  "description": {
+    "short": "Packing list app",
+    "full": "Test app to test static tabs flow"
+  },
+  "icons": { "outline": "outline.png", "color": "color.png" },
+  "accentColor": "#eff9fc",
+  "staticTabs": [
+    {
+      "entityId": "54d496e0-2b51-4210-bf7d-21d0b5821d9c",
+      "name": "Packing List - PersonalAndMeetingSidePanel",
+      "contentUrl": "https://packing-list.azurewebsites.net",
+      "websiteUrl": "https://packing-list.azurewebsites.net",
+      "scopes": ["personal"],
+      "context": [
+        "meetingSidePanel"
+      ]
+    }
+  ],
+  "validDomains": ["packing-list.azurewebsites.net"],
+  "webApplicationInfo": { "id": "25407c29-8335-68a3-bfdb-4384580a1858" },
+  "showLoadingIndicator": true,
+  "authorization": {
+    "permissions": {
+      "orgWide": [],
+      "resourceSpecific": [
+        { "name": "OnlineMeeting.ReadBasic.Chat", "type": "Delegated" },
+        { "name": "MeetingStage.Write.Chat", "type": "Delegated" },
+        { "name": "OnlineMeetingParticipant.Read.Chat", "type": "Delegated" },
+        {
+          "name": "OnlineMeetingParticipant.ToggleIncomingAudio.Chat",
+          "type": "Delegated"
+        },
+        { "name": "ChannelMeetingStage.Write.Group", "type": "Delegated" },
+        { "name": "ChannelMeeting.ReadBasic.Group", "type": "Delegated" }
+      ]
+    }
+  }
+}
+```
+
+</details>
+
+### Pin your personal tab app to enable calling
+
+Teams client users can access your personal tab app only if it's pinned by the Teams administrator. Administrators can leverage **Calling extensions** to pin personal calling tab apps. To pin an app for calling:
+
+1. Go to the pinned apps section in the app setup policy.
+1. Pin your app and assign it to users who need access during one-on-one calls.
+
+:::image type="content" source="../assets/images/tab-images/pin-tab-calling.png" alt-text="Image shows how to enable calling extensions to pin apps for calling." lightbox="../assets/images/tab-images/pin-tab-calling.png":::
+
+## See also
+
+[Create a tab](../tabs/how-to/create-personal-tab.md)

msteams-platform/apps-in-teams-meetings/meeting-apps-apis.md

@@ -20,9 +20,9 @@ The meeting extensibility provides APIs to enhance meeting experience. You can p
 
 The following table provides a list of APIs available across the Microsoft Teams JavaScript library and Microsoft Bot Framework SDKs:
 
-|Method| Description| Source|
-|---|---|----|
-|[**Get user context**](#get-user-context-api)| Get contextual information to display relevant content in a Microsoft Teams tab.| [TeamsJS library](/javascript/api/@microsoft/teams-js/app?view=msteams-client-js-latest#@microsoft-teams-js-app-getcontext&preserve-view=true) |
+| Method | Description | Source |
+| --- | --- | --- |
+| [**Get user context**](#get-user-context-api) | Get contextual information to display relevant content in a Microsoft Teams tab. | [TeamsJS library](/javascript/api/@microsoft/teams-js/app?view=msteams-client-js-latest#@microsoft-teams-js-app-getcontext&preserve-view=true) |
 |[**Get participant**](#get-participant-api)| Fetch participant information by meeting ID and participant ID. | [Microsoft Bot Framework SDK](/dotnet/api/microsoft.bot.builder.teams.teamsinfo.getmeetingparticipantasync?view=botbuilder-dotnet-stable&preserve-view=true)
 |[**Send in-meeting notification**](#send-an-in-meeting-notification)| Provides meeting signals using the existing conversation notification API for user-bot chat and allows the bot to notify user action that shows an in-meeting notification. | [Microsoft Bot Framework SDK](/dotnet/api/microsoft.bot.builder.teams.teamsactivityextensions.teamsnotifyuser?view=botbuilder-dotnet-stable&preserve-view=true) |
 |[**Get meeting details**](#get-meeting-details-api)| Get a meeting's static metadata. | [Microsoft Bot Framework SDK](/dotnet/api/microsoft.bot.builder.teams.teamsinfo.getmeetinginfoasync?view=botbuilder-dotnet-stable&preserve-view=true) |
@@ -963,12 +963,22 @@ The meeting details API enables your app to get a meeting's static metadata. The
 
 The meeting details API must have a bot registration and bot ID. It requires Bot SDK to get `TurnContext`. To use the meeting details API, you must obtain different RSC permission based on the scope of any meeting, such as private meeting or channel meeting.
 
+**Use `getMeetingDetailsVerbose` for one-to-one calling extensibility**
+
+The `getMeetingDetailsVerbose` function extends the functionality of the `getMeetingDetails` API to enable Public Switched Telephone Network (PSTN) and Teams-to-Teams calls for personal tab apps. Ensure that the optional parameter `shouldGetVerboseDetails` is set to `true`. It returns the `IMeetingDetailsResponse` interface with additional call details.
+
+For more information, see [build tabs for calling](build-tabs-for-calling.md).
+
 > [!NOTE]
 > The meeting details API is supported for scheduled private meetings, scheduled channel meeting, instant meetings (Meet now), one-on-one calls, and group calls in Teams desktop and mobile clients.
 
-### Prerequisite
+### Prerequisites
 
-To use the meeting details API, you must obtain different RSC permission based on the scope of any meeting, such as private meeting or channel meeting.
+* To use the meeting details API, you must obtain different RSC permission based on the scope of any meeting, such as private meeting or channel meeting.
+
+* To enable calling, ensure that you've obtained the `OnlineMeetingParticipant.Read.Chat` RSC permission.
+
+* Teams JS SDK required: [TeamsJS SDK release latest release](https://github.com/OfficeDev/microsoft-teams-library-js/releases/tag/v2.29.0).
 
 <br>
 
@@ -1061,9 +1071,9 @@ Use the following example to configure your app manifest's `webApplicationInfo`
 
 The following table lists the query parameter:
 
-|Value|Type|Required|Description|
-|---|---|----|---|
-|**meetingId**| String | Yes | The meeting identifier is available through Bot Invoke and the TeamsJS library.|
+| Value | Type | Required | Description |
+| --- | --- | --- | --- |
+| **meetingId** | String | Yes | The meeting identifier is available through Bot Invoke and the TeamsJS library. |
 
 ### Example
 
@@ -1093,6 +1103,66 @@ this.onMessage(async(context, next) =>{
 
 ```
 
+**Calling extensibility**:
+
+* **Example for enabling personal tab for calling extensibility**:
+
+    ```JavaScript
+    const GetMeetingDetailsVerbose = (): React.ReactElement =>
+        ApiWithoutInput ({
+            name: 'getMeetingDetailsVerbose'
+            title: 'Get Meeting Details Verbose'
+            onClick: async () => {
+                const result = await meeting.getMeetingDetailsVerbose();
+                return JSON.stringify (result);
+            };
+    });
+    ```
+
+* **`getMeetingDetailsVerbose()` to enable Public Switched Telephone Network (PSTN) and Teams-to-Teams calls**:
+
+    ```JavaScript
+    interface IMeetingOrCallDetailsBase <T> {
+      /**
+       * Scheduled start time of the meeting or start time of the call
+       */
+      scheduledStartTime: string;
+
+      /**
+       * url to join the current call or meeting
+       */
+      joinUrl?: string;
+
+      /**
+       * type of the meeting or call
+       */
+      type?: T;
+    }
+
+    interface ICallDetails
+      extends IMeetingOrCallDetailsBase<MeetingDetailsCallType> {
+      originalCallerInfo?: ICallParticipantIdentifiers;
+      dialedEntityInfo?: ICallParticipantIdentifiers;
+      trackingID?: string;
+      callID?: string;
+    }
+
+    interface iConversation {
+      id: string;
+    }
+
+    interface IOrganizer {
+      id?: string;
+      tenantId?: string;
+    }
+
+    export interface IMeetingDetailsResponse {
+      details: IMeetingDetails | ICallDetails;
+      conversation: IConversation;
+      organizer: IOrganizer;
+    }
+    ```
+
 # [JSON](#tab/json)
 
 ```http
@@ -1248,6 +1318,10 @@ The JSON response body for meeting details API is as follows:
 | **organizer.id** | The Organizer's user ID. |
 | **organizer.aadObjectId** | The Organizer's Microsoft Entra object ID. |
 | **organizer.tenantId** | The Organizer's Microsoft Entra tenant ID. |
+| **shouldGetVerboseDetails** | Optional boolean indicating that the host must return additional call details in the response if it's set to `true`. |
+| **originalCaller** | MRI for the original caller of a call. |
+| **dialedEntity** | MRI that the original called dialed |
+| **trackingId** | A persistent ID that references a call and all of its related calls. |
 
 In case of recurring meeting type:
 
@@ -1551,9 +1625,9 @@ The following examples show how to capture the participant join and leave events
 
 # [Participant join event](#tab/participant-join-event)
 
- * [SDK reference](/dotnet/api/microsoft.bot.builder.teams.teamsactivityhandler.onteamsmeetingparticipantsjoinasync?view=botbuilder-dotnet-stable&preserve-view=true)
+* [SDK reference](/dotnet/api/microsoft.bot.builder.teams.teamsactivityhandler.onteamsmeetingparticipantsjoinasync?view=botbuilder-dotnet-stable&preserve-view=true)
 
- * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/meetings-events/csharp/MeetingEvents/Bots/ActivityBot.cs#L35)
+* [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/meetings-events/csharp/MeetingEvents/Bots/ActivityBot.cs#L35)
 
 ```csharp
 //Invoked on participant join a meeting
@@ -1566,9 +1640,9 @@ protected override async Task OnTeamsMeetingParticipantsJoinAsync(MeetingPartici
 
 # [Participant leave event](#tab/participant-leave-event)
 
- * [SDK reference](/dotnet/api/microsoft.bot.builder.teams.teamsactivityhandler.onteamsmeetingparticipantsleaveasync?view=botbuilder-dotnet-stable&preserve-view=true)
+* [SDK reference](/dotnet/api/microsoft.bot.builder.teams.teamsactivityhandler.onteamsmeetingparticipantsleaveasync?view=botbuilder-dotnet-stable&preserve-view=true)
 
- * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/meetings-events/csharp/MeetingEvents/Bots/ActivityBot.cs#L48)
+* [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/meetings-events/csharp/MeetingEvents/Bots/ActivityBot.cs#L48)
 
 ```csharp
 //Invoked on participant leave a meeting
@@ -1799,6 +1873,10 @@ The following table provides the response codes:
 | **501** | API isn't supported in the current context.|
 | **1000** | App doesn't have proper permissions to allow share to stage.|
 
+## Get meeting details verbose
+
+The toggleIncomingClientAudio API allows an app to toggle the incoming audio state setting for the meeting user from mute to unmute or vice-versa. The API is available through the TeamsJS library.
+
 ## Code sample
 
 |Sample name | Description | .NET | Node.js | Manifest|

msteams-platform/apps-in-teams-meetings/teams-apps-in-meetings.md

@@ -86,13 +86,13 @@ Teams supports access to apps during meeting for the following meeting types:
 * [**Group calls**](https://support.microsoft.com/office/start-a-call-from-a-chat-in-teams-f5138c9d-df4c-43d8-9cf6-53400c1a7798): Calls initiated in a group chat.
 * [**Instant meetings**](https://support.microsoft.com/office/start-an-instant-meeting-in-teams-ff95e53f-8231-4739-87fa-00b9723f4ef5): Meetings initiated through **Meet now** button in Teams calendar.
 * [**Webinar**](https://support.microsoft.com/office/get-started-with-teams-webinars-42f3f874-22dc-4289-b53f-bbc1a69013e3): Webinar initiated through **Webinar** button under **New Meeting** dropdown.
+* [**Calling**](/microsoftteams/cloud-voice-landing-page#public-switched-telephone-network-connectivity-options): Extend Teams Phone to initiate calls outside the organization through PSTN connectivity.
 
 Learn more about [Teams meetings, expiration, and policies](/microsoftteams/meeting-expiration) and [meetings, webinars, and live events](/microsoftteams/quick-start-meetings-live-events).
 > [!NOTE]
 >
 > Apps aren't supported in the following:
 >
-> * [Public Switched Telephone Network (PSTN) Teams calls](/microsoftteams/cloud-voice-landing-page#public-switched-telephone-network-connectivity-options)
 > * [End-to-end encrypted Teams calls](https://support.microsoft.com/office/use-end-to-end-encryption-for-teams-calls-1274b4d2-b5c5-4b24-a376-606fa6728a90)
 > * [Instant channel meetings](https://support.microsoft.com/office/start-an-instant-meeting-in-teams-ff95e53f-8231-4739-87fa-00b9723f4ef5)
 > * Meetings in [shared channel](https://support.microsoft.com/office/what-is-a-shared-channel-in-teams-e70a8c22-fee4-4d6e-986f-9e0781d7d11d)

msteams-platform/tabs/how-to/create-personal-tab.md

@@ -974,7 +974,7 @@ You've completed the tutorial to build a tab app with Blazor.
 
 Starting with manifest version 1.7, developers can rearrange all tabs in their personal app. You can move the **bot chat** tab, which always defaults to the first position, anywhere in the personal app tab header. Two reserved tab `entityId` keywords are declared, **conversations** and **about**.
 
-If you create a bot with a **personal** scope, it appears in the first tab position in a personal app by default. If you want to move it to another position, you must add a static tab object to your manifest with the reserved keyword, **conversations**. The **conversation** tab appears on web and desktop depending on where you add the **conversation** tab in the `staticTabs` array. 
+If you create a bot with a **personal** scope, it appears in the first tab position in a personal app by default. If you want to move it to another position, you must add a static tab object to your manifest with the reserved keyword, **conversations**. The **conversation** tab appears on web and desktop depending on where you add the **conversation** tab in the `staticTabs` array.
 
 ``` JSON
 
@@ -993,6 +993,7 @@ If you create a bot with a **personal** scope, it appears in the first tab posit
 }
 
 ```
+
 > [!NOTE]
 > In mobile, tabs are reordered as defined in `staticTabs`.
 
@@ -1048,6 +1049,12 @@ If a context isn't defined in the app manifest, by default Teams consider the fo
 ]
 ```
 
+## Enable personal tab apps for calling extensibility
+
+You can create personal scope apps that integrate with Public Switched Telephone Network (PSTN) and Teams-to-Teams calls. Use the right scope and context to build apps that utilize tab type, static scope, personal context, and meeting side panels.
+
+For more information, see [build tabs for calling](../../apps-in-teams-meetings/build-tabs-for-calling.md).
+
 ## Customizing your static tab in chats or meetings
 
 To customize your static tab experience in chats, channels, or meetings, you can use the `setConfig` APIs in your tab to update the `contentUrl` and `websiteUrl`. Following is an example: