|
| 1 | +--- |
| 2 | +title: Teams Phone extensibility Troubleshooting |
| 3 | +titleSuffix: An Azure Communication Services document |
| 4 | +description: This article describes most common issues and ways to troubleshoot them with Teams Phone extensibility. |
| 5 | +ms.service: azure-communication-services |
| 6 | +ms.subservice: teams-interop |
| 7 | +ms.date: 05/19/2025 |
| 8 | +ms.author: henikaraa |
| 9 | +ms.custom: public_preview |
| 10 | +services: azure-communication-services |
| 11 | +--- |
| 12 | + |
| 13 | +# Teams Phone extensibility troubleshooting |
| 14 | + |
| 15 | +[!INCLUDE [public-preview-notice.md](../../../includes/public-preview-include-document.md)] |
| 16 | + |
| 17 | +This article describes how to identify and resolve Teams Phone extensibility issues. Errors can stem from the application, Azure Communication Services SDKs, the user environment, or Microsoft Teams configuration settings. |
| 18 | + |
| 19 | +Whether you're experiencing problems with Call Automation or the Calling SDK, this article provides information to help you diagnose and fix these issues. |
| 20 | + |
| 21 | +By understanding the potential sources of errors, you can ensure a smoother and more reliable experience with Teams Phone extensibility. |
| 22 | + |
| 23 | +## Call Automation troubleshooting |
| 24 | + |
| 25 | +For troubleshooting issues related to call automation, see the following resources: |
| 26 | +- [Troubleshooting call end response codes](../../../resources/troubleshooting/voice-video-calling/troubleshooting-codes?pivots=automation): provides detailed information on troubleshooting call end response codes for Call Automation, including common error codes and their meanings. |
| 27 | +- [Known issues](../../voice-video-calling/known-issues-call-automation): outlines known issues with call automation, offering insights into current limitations and workarounds. |
| 28 | + |
| 29 | +## Calling SDK troubleshooting |
| 30 | + |
| 31 | +For troubleshooting issues related to the Calling SDK, see: |
| 32 | +- [Troubleshooting overview](../../../resources/troubleshooting/voice-video-calling/general-troubleshooting-strategies/overview.md): provides an overview of general troubleshooting strategies, helping you identify the root of problems efficiently. |
| 33 | +- [Error codes](../../../resources/troubleshooting/voice-video-calling/general-troubleshooting-strategies/understanding-error-codes.md): explains how to understand error codes and subcodes, offering insights into why errors occur and how to mitigate them. |
| 34 | +- [Known issues](../../voice-video-calling/known-issues-webjs.md): outlines known issues with the WebJS Calling SDK, including limitations and workarounds. |
| 35 | +- [VoIP Call Quality](../../voice-video-calling/troubleshoot-web-voip-quality.md): provides guidance on troubleshooting and improving VoIP call quality. |
| 36 | + |
| 37 | +## Common Teams Phone extensibility issues |
| 38 | + |
| 39 | +### Unable to update CallAutomation SDK to Alpha |
| 40 | + |
| 41 | +1. Download `Azure.Communication.CallAutomation.1.4.0-alpha.20250129.2.nupkg` from [Call Automation Alpha SDKs](https://github.com/Azure/communication-preview/blob/master/Teams%20Phone%20Extensibility/teams-phone-extensibility-quickstart.md#alpha-sdks) in your preferred programming language. |
| 42 | +2. Open your solution in Visual Studio and go to the **Tools** menu, select **NuGet Package Manager**, and then select **Package Manager Console**. For reference, see [Manage NuGet packages with the Visual Studio Package Manager Console](/nuget/consume-packages/install-use-packages-powershell#console-controls). |
| 43 | +3. Go to the Package Manager Console and execute the following (be sure to update the path): |
| 44 | + |
| 45 | + ```dotnetcli |
| 46 | + Install-Package C:\path\to\Azure.Communication.CallAutomation.1.4.0-alpha.20250129.2.nupkg |
| 47 | + ``` |
| 48 | + |
| 49 | +4. Go back to the **Tools** menu, select **NuGet Package Manager**, and select **Manage NuGet Packages for Solution**. When the NuGet package loads, go to the **Installed** tab and make sure `Azure.Communication.CallAutomation` says that 1.4.0-alpha.20250129.2 is the installed version. |
| 50 | + |
| 51 | +### Consent blocked due to Microsoft Entra App permission |
| 52 | + |
| 53 | +If you receive the following error: |
| 54 | + |
| 55 | + The app is trying to access a service '1fd5118e-2576-4263-8130-9503064c837a'(Azure Communication Services) that your organization '{GUID}' lacks a service principal for. Contact your IT Admin to review the configuration of your service subscriptions or consent to the application to create the required service principal. |
| 56 | + |
| 57 | +Your Microsoft Entra ID tenant lacks a service principal for the Azure Communication Services application. To fix this issue, use PowerShell as a Microsoft Entra ID administrator to connect to your tenant. Replace Tenant_ID with an ID of your Microsoft Entra ID tenancy. |
| 58 | + |
| 59 | +```dotnetcli |
| 60 | +Connect-MgGraph -TenantId "Tenant_ID" -Scopes Application.ReadWrite.All |
| 61 | +``` |
| 62 | +If the command isn't found, start PowerShell as an administrator and install the Microsoft Graph package. |
| 63 | + |
| 64 | +```dotnetcli |
| 65 | +Install-Module Microsoft.Graph |
| 66 | +``` |
| 67 | +Then execute the following command to add a service principal to your tenant. Don't modify the GUID of the App ID. |
| 68 | + |
| 69 | +```dotnetcli |
| 70 | +New-MgServicePrincipal -AppId "1fd5118e-2576-4263-8130-9503064c837a" |
| 71 | +``` |
| 72 | + |
| 73 | +### Error 400 code 8523 Invalid request: SourceCallerIdNumber and SourceDisplayName aren't supported |
| 74 | + |
| 75 | +Trying to set caller display name caller ID via CallInvite options return an error: |
| 76 | + |
| 77 | +```rest |
| 78 | + {"error":{"code":"8523","message":"Invalid request, SourceCallerIdNumber and SourceDisplayName are not supported..."}} |
| 79 | +``` |
| 80 | +These parameters aren't currently supported in Teams Phone extensibility. You need to set the second parameter in the `CallInvite` object to `null`: |
| 81 | + |
| 82 | +```csharp |
| 83 | +await answerCallContext.CallConnection.AddParticipantAsync(new CallInvite(new PhoneNumberIdentifier("+133333333"),null)); |
| 84 | +``` |
| 85 | + |
| 86 | +### Error 422 Invalid CommunicationUser identifier specified |
| 87 | + |
| 88 | +When your app places an OBO call, the client gets this error if you try to place a call with a phone number. |
| 89 | + |
| 90 | +Calling OBO feature doesn't support calling from a phone number. In `onBehalfOfOptions` you must set the calling identity as a `MicrosoftTeamsAppIdentifier` type as in the following example: |
| 91 | + |
| 92 | +```csharp |
| 93 | + if (this.elements.onBehalfOfUserInput.value !== null && this.elements.onBehalfOfUserInput.value !== "" ) { |
| 94 | + var onBehalfOfUser = "9da5fbd9-007d-4371-9c55-fe28042aa194"; // The value is the oid GUID of your Resource Account |
| 95 | + if (isMicrosoftTeamsAppIdentifier(onBehalfOfUser)) { |
| 96 | + onBehalfOfOptions = onBehalfOfUser ? { userId: onBehalfOfUser } : undefined; |
| 97 | + if (onBehalfOfOptions) { |
| 98 | + console.log("OBO options provided with app Id: " + (onBehalfOfUser as MicrosoftTeamsAppIdentifier).teamsAppId); |
| 99 | + } |
| 100 | + } else { |
| 101 | + console.error("OBO option ignored, MicrosoftTeamsAppIdentifier type expected"); |
| 102 | + } |
| 103 | + } |
| 104 | + |
| 105 | +``` |
| 106 | + |
| 107 | +### Error 408 subcode 10057 `addParticipants` failed for participant `8:acs` |
| 108 | + |
| 109 | +The issue appears when adding dual persona agent and getting an `AddParticipantFailed` event error with the following message: |
| 110 | + |
| 111 | +```rest |
| 112 | + "resultInformation": { |
| 113 | + "code": 408, |
| 114 | + "subCode": 10057, |
| 115 | + "message": "addParticipants failed for participant 8:acs:(redacted) Underlying reason: Request Timeout. DiagCode: 408#10057.@" |
| 116 | + } |
| 117 | +``` |
| 118 | + |
| 119 | +The most common cause is that you're minting a Custom Teams Endpoint (CTE) token and the client is registering with that token with an `8:orgid` MRI as opposed to a dual persona token. This problem is causing the client to not receive the calls since the MRI was `8:orgid` and the server adding a dual persona MRI with `8:acs`. |
| 120 | + |
| 121 | +### Error 403 code `UserLicenseNotPresentForbidden` when agent logs in to client application |
| 122 | + |
| 123 | +The issue appears when agent attempts to sign in to the agent application. |
| 124 | + |
| 125 | +```rest |
| 126 | + {"error":{"code":"UserLicenseNotPresentForbidden","message":"User Login. Teams is disabled in user licenses"}} |
| 127 | +``` |
| 128 | + |
| 129 | +This issue appears if the agent doesn't have a Teams license assigned or is disabled in Teams. Add the appropriate license and validate if user isn't disabled for Teams access and has all the required [Prerequisites](https://github.com/Azure/communication-preview/blob/master/Teams%20Phone%20Extensibility/teams-phone-extensibility-access-teams-phone.md#prerequisites). |
| 130 | + |
| 131 | +### Error 403 subcode 10105 Connecting Call end reason=NoPermission |
| 132 | + |
| 133 | +The most common root cause of this error is a misconfiguration of the 3P Azure Bot. Follow the steps as defined in this [Teams Phone extensibility](https://github.com/Azure/communication-preview/blob/master/Teams%20Phone%20Extensibility/teams-phone-extensibility-quickstart.md#ccaas-developer-provision-the-appid-application-id), specifically enable the Teams channel. |
| 134 | + |
| 135 | +### Error 400 Bad Requests when adding a Teams Channel in Azure Bot |
| 136 | + |
| 137 | +This issue generally arises if the bot was created with a reserved Microsoft Entra App ID. Delete your bot and recreate it with your Microsoft Entra App ID created or used in [Create Bot](https://github.com/Azure/communication-preview/blob/master/Teams%20Phone%20Extensibility/teams-phone-extensibility-quickstart.md#ccaas-developer-create-the-bot). |
| 138 | + |
| 139 | +### No Incoming Call notification in Call Automation application and a busy signal is heard instead of custom greeting when calling a Teams Service Number |
| 140 | + |
| 141 | +This issue arises when the provisioning of the Resource Account is incomplete or incorrect. Check your [Provisioning Resource Account](https://github.com/Azure/communication-preview/blob/master/Teams%20Phone%20Extensibility/teams-phone-extensibility-quickstart.md#teams-admin-provision-resource-account) and change as needed. |
| 142 | + |
| 143 | +### No Incoming Call notification in Call Automation application and no audio is heard and call disconnects when calling a Teams Service Number |
| 144 | + |
| 145 | +This issue arises when the provisioning of the Resource Account is incomplete or incorrect or failure to grant consent. Check [Provisioning Resource Account](https://github.com/Azure/communication-preview/blob/master/Teams%20Phone%20Extensibility/teams-phone-extensibility-quickstart.md#teams-admin-provision-resource-account) and [Server Consent](https://github.com/Azure/communication-preview/blob/master/Teams%20Phone%20Extensibility/teams-phone-extensibility-access-teams-phone.md#provide-server-consent), making changes as needed. |
| 146 | + |
| 147 | +## Related articles |
| 148 | + |
| 149 | +- [Teams Phone extensibility overview](./teams-phone-overview.md) |
| 150 | +- [Teams Phone extensibility FAQ](./teams-phone-extensibility-faq.md) |
0 commit comments