Troubleshooting in Azure Communication Services

This document will help you troubleshoot issues that you may experience within your Communication Services solution. If you're troubleshooting SMS, you can enable delivery reporting with Event Grid to capture SMS delivery details.

Getting help

We encourage developers to submit questions, suggest features, and report problems as issues. To aid in doing this we have a dedicated support and help options page which lists your options for support.

To help you troubleshoot certain types of issues, you may be asked for any of the following pieces of information:

  • MS-CV ID: This ID is used to troubleshoot calls and messages.
  • Call ID: This ID is used to identify Communication Services calls.
  • SMS message ID: This ID is used to identify SMS messages.
  • Short Code Program Brief ID: This ID is used to identify a short code program brief application.
  • Email message ID: This ID is used to identify Send Email requests.
  • Correlation ID: This ID is used to identify requests made using Call Automation.
  • Call logs: These logs contain detailed information that can be used to troubleshoot calling and network issues.

Also take a look at our service limits documentation for more information on throttling and limitations.

Access your MS-CV ID

The MS-CV ID can be accessed by configuring diagnostics in the clientOptions object instance when initializing your SDKs. Diagnostics can be configured for any of the Azure SDKs including Chat, Identity, and VoIP calling.

Client options example

The following code snippets demonstrate diagnostics configuration. When the SDKs are used with diagnostics enabled, diagnostics details will be emitted to the configured event listener:

// 1. Import Azure.Core.Diagnostics
using Azure.Core.Diagnostics;

// 2. Initialize an event source listener instance
using var listener = AzureEventSourceListener.CreateConsoleLogger();
Uri endpoint = new Uri("https://<RESOURCE-NAME>.communication.azure.net");
var (token, communicationUser) = await GetCommunicationUserAndToken();
CommunicationUserCredential communicationUserCredential = new CommunicationUserCredential(token);

// 3. Setup diagnostic settings
var clientOptions = new ChatClientOptions()
{
    Diagnostics =
    {
        LoggedHeaderNames = { "*" },
        LoggedQueryParameters = { "*" },
        IsLoggingContentEnabled = true,
    }
};

// 4. Initialize the ChatClient instance with the clientOptions
ChatClient chatClient = new ChatClient(endpoint, communicationUserCredential, clientOptions);
ChatThreadClient chatThreadClient = await chatClient.CreateChatThreadAsync("Thread Topic", new[] { new ChatThreadMember(communicationUser) });

Access IDs required for Call Automation

When troubleshooting issues with the Call Automation SDK, like call management or recording problems, you'll need to collect the IDs that help identify the failing call or operation. You can provide either of the two IDs mentioned here.

  • From the header of API response, locate the field X-Ms-Skype-Chain-Id.

    Screenshot of response header showing X-Ms-Skype-Chain-Id.

  • From the callback events your application receives after executing an action e.g. CallConnected or PlayFailed, locate the correlationID.

    Screenshot of call disconnected event showing correlation ID.

In addition to one of these IDs, please provide the details on the failing use case and the timestamp for when the failure was observed.

Access your client call ID

When troubleshooting voice or video calls, you may be asked to provide a call ID. This can be accessed via the id property of the call object:

// `call` is an instance of a call created by `callAgent.startCall` or `callAgent.join` methods
console.log(call.id)

Access your SMS message ID

For SMS issues, you can collect the message ID from the response object.

// Instantiate the SMS client
const smsClient = new SmsClient(connectionString);
async function main() {
  const result = await smsClient.send({
    from: "+18445792722",
    to: ["+1972xxxxxxx"],
    message: "Hello World 👋🏻 via Sms"
  }, {
    enableDeliveryReport: true // Optional parameter
  });
console.log(result); // your message ID will be in the result
}

Access your short code program brief ID

The program brief ID can be found on the Azure portal in the Short Codes blade.

Screenshot showing a short code program brief ID.


Access your email message ID

When troubleshooting send email or email message status requests, you may be asked to provide a message ID. This can be accessed in the response:

Console.WriteLine($"MessageId = {emailResult.MessageId}");

Enable and access call logs

The Azure Communication Services Calling SDK relies internally on @azure/logger library to control logging. Use the setLogLevel method from the @azure/logger package to configure the log output:

import { setLogLevel } from '@azure/logger';
setLogLevel('verbose');
const callClient = new CallClient();

You can use AzureLogger to redirect the logging output from Azure SDKs by overriding the AzureLogger.log method: This may be useful if you want to redirect logs to a location other than console.

import { AzureLogger } from '@azure/logger';
// redirect log output
AzureLogger.log = (...args) => {
  console.log(...args); // to console, file, buffer, REST API..
};

Enable and access call logs (Windows)

When developing for Windows, your logs are stored in .blog files. Note that you can't view the logs directly because they're encrypted.

These can be accessed by looking at where your app is keeping its local data. There are many ways to figure out where a UWP app keeps its local data, the following steps are just one of these ways:

  1. Open a Windows Command Prompt (Windows Key + R)
  2. Type cmd.exe
  3. Type where /r %USERPROFILE%\AppData acs*.blog
  4. Please check if the app ID of your application matches with the one returned by the previous command.
  5. Open the folder with the logs by typing start followed by the path returned by the step 3. For example: start C:\Users\myuser\AppData\Local\Packages\e84000dd-df04-4bbc-bf22-64b8351a9cd9_k2q8b5fxpmbf6
  6. Please attach all the *.blog and *.etl files to your Azure support request.

Finding Azure Active Directory information

  • Getting Directory ID
  • Getting Application ID
  • Getting User ID

Getting Directory ID

To find your Directory (tenant) ID, follow the steps listed below:

  1. Navigate to Azure portal and sign in to the Azure portal using the credentials.

  2. From the left-pane, select Azure Active Directory.

  3. From Overview page in Azure AD, copy the Directory (tenant) ID and store it in your application code.

    Screenshot of how to copy Azure Active Directory tenant ID and store it.

Getting Application ID

To find your Application ID, follow the steps listed below:

  1. Navigate to Azure portal and sign in to the Azure portal using the credentials.

  2. From the left-pane, select Azure Active Directory.

  3. From App registrations in Azure AD, select your application.

  4. Copy the Application ID and store it in your application code.

    Screenshot of how to copy Azure Active Directory application ID and store it.

    The directory (tenant) ID can also be found in the application overview page.

Getting User ID

To find your User ID, follow the steps listed below:

  1. Navigate to Azure portal and sign in to the Azure portal using the credentials.

  2. From the left-pane, select Azure Active Directory.

  3. From Users in Azure AD, select your user.

  4. From Profile page in Azure AD Users, copy the Object ID and store it in your application code.

    Screenshot of how to copy Azure Active Directory user ID and store it.

Getting immutable resource ID

Sometimes you also need to provide immutable resource ID of your Communication Service resource. To find it, follow the steps listed below:

  1. Navigate to Azure portal and sign in to the Azure portal using the credentials.
  2. Open your Communication Service resource.
  3. From the left-pane, select Overview, and switch to a JSON view Screenshot of how to switch Communication Resource overview to a JSON view.
  4. From Resource JSON page, copy the immutableResourceId value, and provide it to your support team. Screenshot of Resource JSON.

Verification of Teams license eligibility to use Azure Communication Services support for Teams users

There are two ways to verify your Teams License eligibility to use Azure Communication Services support for Teams users:

  • Verification via Teams web client
  • Checking your current Teams license via Microsoft Graph API

Verification via Teams web client

To verify your Teams License eligibility via Teams web client, follow the steps listed below:

  1. Open your browser and navigate to Teams web client.
  2. Sign in with credentials that have a valid Teams license.
  3. If the authentication is successful and you remain in the https://teams.microsoft.com/ domain, then your Teams License is eligible. If authentication fails or you're redirected to the https://teams.live.com/v2/ domain, then your Teams License isn't eligible to use Azure Communication Services support for Teams users.

Checking your current Teams license via Microsoft Graph API

You can find your current Teams license using licenseDetails Microsoft Graph API that returns licenses assigned to a user. Follow the steps below to use the Graph Explorer tool to view licenses assigned to a user:

  1. Open your browser and navigate to Graph Explorer

  2. Sign in to Graph Explorer using the credentials. Screenshot of how to sign in to Graph Explorer.

  3. In the query box, enter the following API and click Run Query :

    https://graph.microsoft.com/v1.0/me/licenseDetails
    

    Screenshot of how to enter API in Graph Explorer.

    Or you can query for a particular user by providing the user ID using the following API:

    https://graph.microsoft.com/v1.0/users/{id}/licenseDetails
    
  4. The Response preview pane displays output as follows:

    Note that the response object shown here might be shortened for readability.

    {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('071cc716-8147-4397-a5ba-b2105951cc0b')/assignedLicenses",
        "value": [
            {
                "skuId": "b05e124f-c7cc-45a0-a6aa-8cf78c946968",
                "servicePlans":[
                    {
                        "servicePlanId":"57ff2da0-773e-42df-b2af-ffb7a2317929",
                        "servicePlanName":"TEAMS1",
                        "provisioningStatus":"Success",
                        "appliesTo":"User"
                    }
                ]
            }
        ]
    }
    
  5. Find license detail where property servicePlanName has one of the values in the Eligible Teams Licenses table

Calling SDK error codes

The Azure Communication Services Calling SDK uses the following error codes to help you troubleshoot calling issues. These error codes are exposed through the call.callEndReason property after a call ends.

Error code Description Action to take
403 Forbidden / Authentication failure. Ensure that your Communication Services token is valid and not expired.
404 Call not found. Ensure that the number you're calling (or call you're joining) exists.
408 Call controller timed out. Call Controller timed out waiting for protocol messages from user endpoints. Ensure clients are connected and available.
410 Local media stack or media infrastructure error. Ensure that you're using the latest SDK in a supported environment.
430 Unable to deliver message to client application. Ensure that the client application is running and available.
480 Remote client endpoint not registered. Ensure that the remote endpoint is available.
481 Failed to handle incoming call. File a support request through the Azure portal.
487 Call canceled, locally declined, ended due to an endpoint mismatch issue, or failed to generate media offer. Expected behavior.
490, 491, 496, 487, 498 Local endpoint network issues. Check your network.
500, 503, 504 Communication Services infrastructure error. File a support request through the Azure portal.
603 Call globally declined by remote Communication Services participant Expected behavior.

Call Automation SDK error codes

The below error codes are exposed by Call Automation SDK.

Error Code Description Actions to take
400 Bad request The input request is invalid. Look at the error message to determine which input is incorrect.
400 Play Failed Ensure your audio file is WAV, 16KHz, Mono and make sure the file url is publicly accessible.
400 Recognize Failed Check the error message. The message will highlight if this is due to timeout being reached or if operation was canceled. For more information about the error codes and messages you can check our how-to guide for gathering user input.
401 Unauthorized HMAC authentication failed. Verify whether the connection string used to create CallAutomationClient is correct.
403 Forbidden Request is forbidden. Make sure that you can have access to the resource you are trying to access.
404 Resource not found The call you are trying to act on doesn't exist. For example, transferring a call that has already disconnected.
429 Too many requests Retry after a delay suggested in the Retry-After header, then exponentially backoff.
500 Internal server error Retry after a delay. If it persists, raise a support ticket.
500 Play Failed File a support request through the Azure portal.
500 Recognize Failed Check error message and confirm the audio file format is valid (WAV, 16KHz, Mono), if the file format is valid then file a support request through Azure portal.
502 Bad gateway Retry after a delay with a fresh http client.

Consider the below tips when troubleshooting certain issues.

  • Your application is not getting IncomingCall Event Grid event: Make sure the application endpoint has been validated with Event Grid at the time of creating event subscription. The provisioning status for your event subscription will be marked as succeeded if the validation was successful.
  • Getting the error 'The field CallbackUri is invalid': Call Automation does not support HTTP endpoints. Make sure the callback url you provide supports HTTPS.
  • PlayAudio action does not play anything: Currently only Wave file (.wav) format is supported for audio files. The audio content in the wave file must be mono (single-channel), 16-bit samples with a 16,000 (16KHz) sampling rate.
  • Actions on PSTN endpoints aren't working: CreateCall, Transfer, AddParticipant and Redirect to phone numbers require you to set the SourceCallerId in the action request. Unless you are using Direct Routing, the source caller ID should be a phone number owned by your Communication Services resource for the action to succeed.

Refer to this article to learn about any known issues being tracked by the product team.

Chat SDK error codes

The Azure Communication Services Chat SDK uses the following error codes to help you troubleshoot chat issues. The error codes are exposed through the error.code property in the error response.

Error code Description Action to take
401 Unauthorized Ensure that your Communication Services token is valid and not expired.
403 Forbidden Ensure that the initiator of the request has access to the resource.
429 Too many requests Ensure that your client-side application handles this scenario in a user-friendly manner. If the error persists, please file a support request.
503 Service Unavailable File a support request through the Azure portal.

SMS error codes

The Azure Communication Services SMS SDK uses the following error codes to help you troubleshoot SMS issues. The error codes are exposed through the "DeliveryStatusDetails" field in the SMS delivery report.

Error code Description Action to take
2000 Message Delivered Successfully
4000 Message is rejected due to fraud detection Ensure you aren't exceeding the maximum number of messages allowed for your number
4001 Message is rejected due to invalid Source/From number format Ensure the To number is in E.164 format and From number format is in E.164 or Short code format
4002 Message is rejected due to invalid Destination/To number format Ensure the To number is in E.164 format
4003 Message failed to deliver due to unsupported destination Check if the destination you're trying to send to is supported
4004 Message failed to deliver since Destination/To number doesn't exist Ensure the To number you're sending to is valid
4005 Message is blocked by Destination carrier
4006 The Destination/To number isn't reachable Try resending the message at a later time
4007 The Destination/To number has opted out of receiving messages from you Mark the Destination/To number as opted out so that no further message attempts are made to the number
4008 You've exceeded the maximum number of messages allowed for your profile Ensure you aren't exceeding the maximum number of messages allowed for your number or use queues to batch the messages
4009 Message is rejected by Microsoft Entitlement System Most often it happens if fraudulent activity is detected. Please contact support for more details
4010 Message was blocked due to the toll-free number not being verified Review unverified sending limits and submit toll-free verification as soon as possible
5000 Message failed to deliver. Please reach out Microsoft support team for more details File a support request through the Azure portal
5001 Message failed to deliver due to temporary unavailability of application/system
5002 Message Delivery Timeout Try resending the message
9999 Message failed to deliver due to unknown error/failure Try resending the message