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.
  • 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 your server call ID

When troubleshooting issues with the Call Automation SDK, like call recording and call management problems, you will need to collect the Server Call ID. This ID can be collected using the getServerCallId method.

JavaScript

callAgent.on('callsUpdated', (e: { added: Call[]; removed: Call[] }): void => {
    e.added.forEach((addedCall) => {
        addedCall.on('stateChanged', (): void => {
            if (addedCall.state === 'Connected') {
                addedCall.info.getServerCallId().then(result => {
                    dispatch(setServerCallId(result));
                }).catch(err => {
                    console.log(err);
                });
            }
        });
    });
});

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.

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.

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.

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 are not 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 are trying to send to is supported
4004 Message failed to deliver since Destination/To number does not exist Ensure the To number you are sending to is valid
4005 Message is blocked by Destination carrier
4006 The Destination/To number is not reachable Try re-sending 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 have exceeded the maximum number of messages allowed for your profile Ensure you are not exceeding the maximum number of messages allowed for your number or use queues to batch the messages
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 re-sending the message
9999 Message failed to deliver due to unknown error/failure Try re-sending the message