Uredi

Teams Phone extensibility troubleshooting

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.

Whether you're experiencing problems with Call Automation or the Calling SDK, this article provides information to help you diagnose and fix these issues.

By understanding the potential sources of errors, you can ensure a smoother and more reliable experience with Teams Phone extensibility.

Call Automation troubleshooting

For troubleshooting issues related to call automation, see the following resources:

  • Troubleshooting call end response codes: provides detailed information on troubleshooting call end response codes for Call Automation, including common error codes and their meanings.
  • Known issues: outlines known issues with call automation, offering insights into current limitations and workarounds.

Calling SDK troubleshooting

For troubleshooting issues related to the Calling SDK, see:

  • Troubleshooting overview: provides an overview of general troubleshooting strategies, helping you identify the root of problems efficiently.
  • Error codes: explains how to understand error codes and subcodes, offering insights into why errors occur and how to mitigate them.
  • Known issues: outlines known issues with the WebJS Calling SDK, including limitations and workarounds.
  • VoIP Call Quality: provides guidance on troubleshooting and improving VoIP call quality.

Common Teams Phone extensibility issues

If you receive the following error:

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.

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.

Connect-MgGraph -TenantId "Tenant_ID" -Scopes Application.ReadWrite.All

If the command isn't found, start PowerShell as an administrator and install the Microsoft Graph package.

Install-Module Microsoft.Graph

Then execute the following command to add a service principal to your tenant. Don't modify the GUID of the App ID.

New-MgServicePrincipal -AppId "1fd5118e-2576-4263-8130-9503064c837a"

Error 404 subcode 5804xx: Blocked Outbound Calls

These errors typically occur when the resource account does not have an active funding source for outbound calls. The funding source depends on the customer’s agreement type:

  • If the customer has an MCA agreement:

    • Ensure a postpaid payment method is in place.
    • Ensure the tenant has a Microsoft Teams Calling Plan (Pay-As-You-Go) license.
    • Ensure the Pay-As-You-Go Calling Plan license is assigned to the resource account.

  • If the customer has an older agreement:

    • Ensure the tenant has a Communications Credits license.
    • Ensure the Communications Credits balance is positive (funds are loaded).

Outbound calling in Teams Phone Extensibility requires one of these funding sources to be correctly configured. If not set properly, you may see one of the below error subcodes:

Error Code Meaning Fix
580406 Balance not found Check funding source setup (MCA or Communications Credits)
580462 No enabled tenant capabilities Assign Communications Credits license to tenant
580464 No enabled user capabilities Assign Communications Credits license to user

You can follow the below steps to solve this:

1. Sign in to Microsoft 365 Admin Center

Log in with your admin credentials: https://admin.microsoft.com

2. Verify agreement type and funding source

  • For MCA agreements:

    • Confirm postpaid payment method is active.
    • Navigate to Marketplace → All Products.
    • Search for Microsoft Teams Calling Plan (Pay-As-You-Go).
    • Select the appropriate Pay-As-You-Go Calling Plan Zone (Zone 1 or Zone 2) based on your location.
    • Add the plan under Add-ons.
      More details: Learn more about Calling Plans pay-as-you-go

  • For older agreements:

    • Navigate to Marketplace → All Products and purchase Communications Credits.
    • Add funds to ensure a positive balance.
    • Enable Auto-Recharge under Billing → Your Products → Communications Credits.
      More details: Set up Communications Credits

3. Assign Licenses to Resource Account

  • Go to Users → Active Users.
  • Assign:
    • Microsoft Teams Calling Plan (Pay-As-You-Go)
    • Microsoft Teams Phone Resource Account
  • Important: Remove any other conflicting calling plans.
    More details: Assign licenses to users

Error 403 subcode 510586: Blocked Outbound Calls from Operator Connect Carrier

This error indicates that outbound PSTN calls are being blocked by your Operator Connect carrier. This typically occurs when there are restrictions or issues with your carrier’s configuration or account status. This can be caused by:

  • Carrier-imposed restrictions on outbound calling.
  • Account suspension or insufficient balance with the carrier.
  • Incorrect configuration of Operator Connect settings.

Error 400 code 8523 Invalid request: SourceCallerIdNumber and SourceDisplayName aren't supported

Trying to set caller display name caller ID via CallInvite options return an error:

   {"error":{"code":"8523","message":"Invalid request, SourceCallerIdNumber and SourceDisplayName are not supported..."}}

These parameters aren't currently supported in Teams Phone extensibility. You need to set the second parameter in the CallInvite object to null:

await answerCallContext.CallConnection.AddParticipantAsync(new CallInvite(new PhoneNumberIdentifier("+133333333"),null));

Error 422 Invalid CommunicationUser identifier specified

When your app places an OBO call, the client gets this error if you try to place a call with a phone number.

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:

 if (this.elements.onBehalfOfUserInput.value !== null && this.elements.onBehalfOfUserInput.value !== "" ) {
     var onBehalfOfUser = "9da5fbd9-007d-4371-9c55-fe28042aa194"; // The value is the oid GUID of your Resource Account
     if (isMicrosoftTeamsAppIdentifier(onBehalfOfUser)) {
         onBehalfOfOptions = onBehalfOfUser ? { userId: onBehalfOfUser } : undefined;
         if (onBehalfOfOptions) {
             console.log("OBO options provided with app Id: " + (onBehalfOfUser as MicrosoftTeamsAppIdentifier).teamsAppId);
         }
     } else {
         console.error("OBO option ignored, MicrosoftTeamsAppIdentifier type expected");
     }
  }

Error 408 subcode 10057 addParticipants failed for participant 8:acs

The issue appears when adding dual persona agent and getting an AddParticipantFailed event error with the following message:

    "resultInformation": {
      "code": 408,
      "subCode": 10057,
      "message": "addParticipants failed for participant 8:acs:(redacted) Underlying reason: Request Timeout. DiagCode: 408#10057.@"
    }

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.

Error 403 code UserLicenseNotPresentForbidden when agent logs in to client application

The issue appears when agent attempts to sign in to the agent application.

   {"error":{"code":"UserLicenseNotPresentForbidden","message":"User Login. Teams is disabled in user licenses"}}

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.

Error 403 subcode 10105 Connecting Call end reason=NoPermission

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, specifically enable the Teams channel.

Error 400 Bad Requests when adding a Teams Channel in Azure Bot

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.

No Incoming Call notification in Call Automation application and a busy signal is heard instead of custom greeting when calling a Teams Service Number

This issue arises when the provisioning of the Resource Account is incomplete or incorrect. Check your Provisioning Resource Account and change as needed.

No Incoming Call notification in Call Automation application and no audio is heard and call disconnects when calling a Teams Service Number

This issue arises when the provisioning of the Resource Account is incomplete or incorrect or failure to grant consent. Check Provisioning Resource Account and Server Consent, making changes as needed.

  • Last updated on