Chat Connectivity Checklist (First 10 Minutes)¶

When chat messages are delayed or connectivity fails, follow this initial checklist.

Immediate Checklist¶

1. Access Token Validity: Has the user's token expired? (Typically lasts 24h)
2. Thread Existence: Does the chat thread still exist and is the user a participant?
3. Participant Permissions: Does the user have the required role (e.g., member) to send messages?
4. Network Connectivity: Is the client's WebSocket connection blocked by a firewall?
5. Real-time Event Subscription: Is the app listening for incoming messages correctly?

Essential Diagnostic Steps¶

flowchart TD
    S["Chat client cannot connect"] --> C1{"Access token still valid?"}
    C1 -- no --> A1["Refresh the access token"]
    C1 -- yes --> C2{"Thread exists and user is a participant?"}
    C2 -- no --> A2["Rejoin or recreate the thread"]
    C2 -- yes --> C3{"Participant has the required role?"}
    C3 -- no --> A3["Grant the member role"]
    C3 -- yes --> C4{"WebSocket blocked by firewall?"}
    C4 -- yes --> A4["Open egress for the WebSocket"]
    C4 -- no --> C5{"App listening for incoming messages?"}
    C5 -- no --> A5["Fix real-time event subscription"]
    C5 -- yes --> ESC["Escalate to the Chat playbooks"]

1. Check Browser Console¶

Open the developer tools and look for 401 Unauthorized or 403 Forbidden errors.

2. Verify Token Scopes¶

Ensure the token has the chat scope when it was generated.

# Issue a fresh access token with the chat scope to validate token issuance
az communication user-identity token issue --scope chat --connection-string "<your_connection_string>"

3. Check Network Traffic¶

Look for failed requests to *.communication.azure.com. If WebSockets are blocked, chat will fail.

Key KQL Queries¶

Run this to see chat message failures:

ACSChatMessageSentEvents
| where TimeGenerated > ago(1h)
| where ResultType == "Failed"
| summarize Count=count() by ResultSignature, ThreadId
| order by Count desc

See Also¶

• Chat Message Delivery Playbook
• Real-time Notifications Playbook

Sources¶

• Azure Communication Services Chat SDK Troubleshooting
• Real-time Messaging Network Requirements