Skip to content

Commit 89fbf21

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #270507 from enricohuang/patch-22
Add troubleshooting guide for Azure Communication Services Web Calling SDK - call setup issues
2 parents e3af779 + 67994c6 commit 89fbf21

File tree

6 files changed

+193
-0
lines changed

6 files changed

+193
-0
lines changed

‎articles/communication-services/resources/troubleshooting/voice-video-calling/call-setup-issues/call-setup-takes-too-long.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Call setup issues - The call setup takes too long
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot when the call setup takes too long.
5+
author: sloanster
6+
ms.author: micahvivion
7+
8+
services: azure-communication-services
9+
ms.date: 04/10/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# The call setup takes too long
16+
When the user makes a call or accepts a call, multiple steps and messages are exchanged between the signaling layer and media transport.
17+
If the call setup takes too long, it's often due to network issues.
18+
Another factor that contributes to call setup delay is the stream acquisition delay, which is the time it takes for a browser to get the media stream.
19+
Additionally, device performance can also affect call setup time. For example, a busy browser may take longer to schedule the API request, resulting in a longer call setup time.
20+
21+
## How to detect using the SDK
22+
The application can calculate the delay between when the call is initiated and when it's connected.
23+
24+
## How to mitigate or resolve
25+
If a user consistently experiences long call setup times, they should check their network for issues such as slow network speed, long round trip time, or high packet loss.
26+
These issues can affect call setup time because the signaling layer uses a `TCP` connection, and factors such as retransmissions can cause delays.
27+
Additionally, if the user suspects the delay comes from stream acquisition, they should check their devices. For example, they can choose a different audio input device.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/call-setup-issues/failed-to-create-call-agent.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
title: Call setup issues - Failed to create CallAgent
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot failed to create CallAgent.
5+
author: sloanster
6+
ms.author: micahvivion
7+
8+
services: azure-communication-services
9+
ms.date: 04/10/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# Failed to create CallAgent
16+
17+
In order to make or receive a call, a user needs a call agent (`CallAgent`).
18+
To create a call agent, the application needs a valid ACS communication token credential. With the token, the application invokes `CallClient.createCallAgent` API to create an instance of `CallAgent`.
19+
It's important to note that multiple call agents aren't currently supported in one `CallClient` object.
20+
21+
## How to detect errors
22+
23+
The `CallClient.createCallAgent` API throws an error if SDK detects an error when creating a call agent.
24+
25+
The possible error code/subcode are
26+
27+
|Code | Subcode| Message | Error category|
28+
|-----------------------------|------- |--------------|---------------|
29+
| 409 (Conflict) | 40228 | Failed to create CallAgent, an instance of CallAgent associated with this identity already exists. | ExpectedError|
30+
| 408 (Request Timeout) | 40104 | Failed to create CallAgent, timeout during initialization of the calling user stack.| UnexpectedClientError|
31+
| 500 (Internal Server Error) | 40216 | Failed to create CallAgent.| UnexpectedClientError |
32+
| 401 (Unauthorized) | 44110 | Failed to get AccessToken | UnexpectedClientError |
33+
| 408 (Request Timeout) | 40114 | Failed to connect to Azure Communication Services infrastructure, timeout during initialization. | UnexpectedClientError |
34+
| 403 (Forbidden) | 40229 | CallAgent must be created only with ACS token | ExpectedError |
35+
| 408 (Request Timeout) | 40114 | Failed to connect to Azure Communication Services infrastructure, timeout during initialization. | UnexpectedClientError |
36+
| 403 (Forbidden) | 40229 | CallAgent must be created only with ACS token | ExpectedError |
37+
| 412 (Precondition Failed) | 40115 | Failed to create CallAgent, unable to initialize connection to Azure Communication Services infrastructure.| UnexpectedClientError |
38+
| 403 (Forbidden) | 40231 | TeamsCallAgent must be created only with Teams token | ExpectedError |
39+
| 401 (Unauthorized) | 44114 | Wrong AccessToken scope format. Scope is expected to be a string that contains `voip` | ExpectedError |
40+
| 400 (Bad Request) | 44214 | Teams users can't set display name. | ExpectedError |
41+
| 500 (Internal Server Error) | 40102 | Failed to create CallAgent, failure during initialization of the calling base stack.| UnexpectedClientError |
42+
43+
## How to mitigate or resolve
44+
45+
The application should catch errors thrown by `createCallAgent` API and display a warning message.
46+
Depending on the reason for the error, the application may need to retry the operation or fix the error before proceeding.
47+
In general, if the error category is `UnexpectedClientError`, it's still possible to create a call agent successfully after a retry.
48+
However, if the error category is `ExpectedError`, there may be errors in the precondition or the data passed in the parameter that need to be fixed on application's side before a call agent can be created.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/call-setup-issues/invalid-or-expired-tokens.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: Call setup issues - Invalid or expired tokens
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot token issues.
5+
author: sloanster
6+
ms.author: micahvivion
7+
8+
services: azure-communication-services
9+
ms.date: 04/10/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# Invalid or expired tokens
16+
Invalid or expired tokens can prevent the ACS Calling SDK from accessing its service. To avoid this issue, your application must use a valid user access token.
17+
It's important to note that access tokens have an expiration time of 24 hours by default.
18+
If necessary, you can adjust the lifespan of tokens issued for your application by creating a short-lived token.
19+
However, if you have a long-running call that could exceed the lifetime of the token, you need to implement refreshing logic in your application.
20+
21+
## How to detect using the SDK
22+
When the application calls `createCallAgent` API, if the token is expired, SDK throws an error.
23+
The error code/subcode is
24+
25+
| error | Details |
26+
|------------------|-------------------------------------------------------|
27+
| code | 401 (UNAUTHORIZED) |
28+
| subcode | 40235 |
29+
| message | AccessToken expired |
30+
31+
When the signaling layer detects the access token expiry, it might change its connection state.
32+
The application can subscribe to the [connectionStateChanged](/javascript/api/azure-communication-services/%40azure/communication-calling/callagent#@azure-communication-calling-callagent-on-2) event. If the connection state changes due to the token expiry, you can see the `reason` field in the `connectionStateChanged` event is `invalidToken`.
33+
34+
## How to mitigate or resolve
35+
If you have a long-running call that could exceed the lifetime of the token, you need to implement refreshing logic in your application.
36+
For handling the token refresh, see [Credentials in Communication SDKs](../../../../concepts/credentials-best-practices.md).
37+
38+
If you encounter this error while creating callAgent, you need to review the token creation logic in your application.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/call-setup-issues/no-incoming-call-notifications.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Call setup issues - The user doesn't receive incoming call notifications
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Learn how to troubleshoot when the user doesn't receive incoming call notifications.
5+
author: sloanster
6+
ms.author: micahvivion
7+
8+
services: azure-communication-services
9+
ms.date: 04/10/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# The user doesn't receive incoming call notifications
16+
If the user isn't receiving incoming call notifications, it may be due to an issue with their network.
17+
Normally, when an incoming call is received, the application should receive an `incomingCall` event through the signaling connection.
18+
However, if the user's network is experiencing problems, such as disconnection or firewall issues, they may not be able to receive this notification.
19+
20+
## How to detect using the SDK
21+
The application can listen the [connectionStateChanged event](/javascript/api/azure-communication-services/@azure/communication-calling/callagent?view=azure-communication-services-js&preserve-view=true#@azure-communication-calling-callagent-on-2) on callAgent object.
22+
If the connection state isn't `Connected`, the user can't receive incoming call notifications.
23+
24+
## How to mitigate or resolve
25+
This error happens when the signaling connection fails.
26+
The application can listen for the `connectionStateChanged` event and display a warning message when the connection state isn't `Connected`.
27+
It could be because the token is expired. The app should fix this issue if it receives tokenExpired event.
28+
Other reasons, such as network issues, users should check their network to see if the disconnection is due to poor connectivity or other network issues.

‎articles/communication-services/resources/troubleshooting/voice-video-calling/call-setup-issues/overview.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Call setup issues - Overview
3+
titleSuffix: Azure Communication Services - Troubleshooting Guide
4+
description: Overview of call setup issues
5+
author: sloanster
6+
ms.author: micahvivion
7+
8+
services: azure-communication-services
9+
ms.date: 04/10/2024
10+
ms.topic: troubleshooting
11+
ms.service: azure-communication-services
12+
ms.subservice: calling
13+
---
14+
15+
# Overview of call setup issues
16+
When an application makes a call with Azure Communication Services WebJS SDK, the first step is to create a `CallClient` instance and use it to create a call agent.
17+
When a call agent is created, the SDK registers the user with the service, allowing other users to reach them.
18+
When the user joins or accepts a call, the SDK establishes media sessions between the two endpoints.
19+
If a user is unable to connect to a call, it's important to determine at which stage the issue is occurring.
20+
21+
## Common issues in call setup
22+
Here we list several common call setup issues, along with potential causes for each issue:
23+
24+
### Invalid or expired tokens
25+
* The application doesn't provide a valid token.
26+
* The application doesn't implement token refresh correctly.
27+
28+
### Failed to create callAgent
29+
* The application doesn't provide a valid token.
30+
* The application creates multiple call agents with a `CallClient` instance.
31+
* The application creates multiple call agents with the same ACS identity on the same page.
32+
* The SDK fails to connect to the service infrastructure.
33+
34+
### The user doesn't receive incoming call notifications
35+
* There's an expired token.
36+
* There's an issue with the signaling connection.
37+
38+
### The call setup takes too long
39+
* The user is experiencing network issues.
40+
* The browser takes a long time to acquire the stream.

‎articles/communication-services/toc.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1057,6 +1057,18 @@ items:
10571057
href: resources/troubleshooting/voice-video-calling/general-troubleshooting-strategies/report-issue.md
10581058
- name: Calling (JavaScript)
10591059
items:
1060+
- name: Call setup issues
1061+
items:
1062+
- name: Overview
1063+
href: resources/troubleshooting/voice-video-calling/call-setup-issues/overview.md
1064+
- name: Invalid or expired tokens
1065+
href: resources/troubleshooting/voice-video-calling/call-setup-issues/invalid-or-expired-tokens.md
1066+
- name: Failed to create callAgent
1067+
href: resources/troubleshooting/voice-video-calling/call-setup-issues/failed-to-create-call-agent.md
1068+
- name: The user doesn't receive incoming call notifications
1069+
href: resources/troubleshooting/voice-video-calling/call-setup-issues/no-incoming-call-notifications.md
1070+
- name: The call setup takes too long
1071+
href: resources/troubleshooting/voice-video-calling/call-setup-issues/call-setup-takes-too-long.md
10601072
- name: Device and permission issues
10611073
items:
10621074
- name: Overview

0 commit comments

Comments
 (0)