Basic Troubleshooting

First-line fixes for the most common phone-system and VoiceAI issues: call quality, audio problems, dropped or failed calls, devices that won't register, and AI agent quirks. Most issues in this guide can be resolved without contacting support.

This guide is written for support reps and admins who manage a DialStack-powered phone system. It is also safe to share directly with end customers; the language and steps are designed for both.

If you're configuring the system rather than fixing it, you probably want the Admin Guide instead.

How to use this guide

Most calls into support fall into one of four patterns:

1. The audio is bad. Choppy, robotic, garbled, echoey, or one direction is silent.
2. The call didn't work. It dropped, never connected, never rang the right person, or never rang at all.
3. A device or app is broken. A desk phone won't boot or register, the softphone won't sign in, a handset shows the wrong user.
4. The AI agent isn't behaving. It won't answer, hangs up early, transcribes wrong, or doesn't transfer correctly.

The fastest path is almost always the same:

1. Run the quick triage below to figure out the shape of the problem.
2. Open the Call Quality dashboard in the admin portal to see whether the numbers confirm what the customer is reporting.
3. Jump to the matching symptom section.
4. If you can't resolve it yourself, use the information to collect before escalating checklist so the team has what they need on the first reply.

Quick triage (start here)

Before doing anything else, answer these four questions. Your answers point you at the right section.

1. Is the platform up? Check the status page at status.dialstack.ai. If many customers across multiple locations are reporting the same problem at the same time, it may be platform- or carrier-side, so check status first before going deeper. If it's clearly localized to one customer, keep going.

2. How many people are affected?

• One person at one location: most likely a device, headset, network, or user-config issue. Start with Audio and call-quality symptoms or Device and app symptoms.
• Multiple people at one location: most likely the customer's local network or internet. Start with Customer network diagnostics.
• Multiple people across multiple locations: could be a regional carrier or platform issue. Re-check the status page, then collect data and escalate.

3. Did anything change recently? A new router, an ISP change, a new firewall, a Wi-Fi reconfiguration, a phone moved to a new location, an admin update to a dial plan. Most "it just started happening" problems trace back to a change in the last 24 to 72 hours.

4. Is it one direction or both?

• Both sides of every call sound bad: network or platform.
• Only one direction can hear: nearly always a NAT, firewall, or routing issue. See One-way audio.
• Only inbound or only outbound calls fail: a routing or dial-plan issue, not network.

Write these four answers down (or note them when you escalate). They speed up every later step.

Open the Call Quality dashboard

Before deep troubleshooting, open the Call Quality dashboard in the admin portal. It gives you a numbers-based picture of what's actually happening.

What to look for:

• Avg. MOS. A single quality score for the selected window. Above 4.0 is good, 3.5 to 4.0 is fair, below 3.5 means real audio problems.
• Avg. Jitter and Avg. Packet Loss. If either is elevated, the customer's network is the most likely cause.
• MOS Over Time chart. Is quality steady or did it dip at a specific time? A sharp drop usually corresponds to a network event, an ISP issue, or a change at the customer's site.
• Lowest Quality Calls table. Pull up the worst calls and click into them. The Call Detail page shows per-leg quality metrics so you can see whether the bad leg was the PSTN side (carrier or platform) or the endpoint side (customer network or device).

How to read the numbers:

MOS	What it means
4.3 – 5.0	Excellent. Indistinguishable from in-person conversation.
4.0 – 4.3	Good. Minor issues, callers unlikely to care.
3.5 – 4.0	Fair. Occasional glitches noticeable.
3.0 – 3.5	Poor. Callers likely to complain.
Below 3.0	Unacceptable. Conversation is difficult.

Where the impairment is:

• High jitter (above 30 ms) usually points to network instability, often Wi-Fi or a congested internet connection.
• Packet loss above 1% is enough to degrade calls noticeably. Above 3% and calls become unusable.
• High round-trip time (above 200 ms) causes the conversational delay where people talk over each other.

If MOS is consistently above 4.0 but the customer is still reporting bad calls, the problem is probably at the device, headset, or speakerphone level rather than the network. Skip to Device and app symptoms.

Network requirements at a glance

What a healthy voice network looks like (bandwidth, the ports and destinations to allow, SIP ALG, NAT keepalives, QoS, Wi-Fi) is documented in full on the Network Requirements guide. That page is the source of truth and is safe to share with a customer's IT contact, so this guide points to it rather than restating it.

The one thing worth keeping in front of you while you troubleshoot is the set of quality thresholds voice is sensitive to. These are the same numbers the Call Quality dashboard reports:

Metric	Acceptable	Problematic
Jitter	Below 30 ms	Above 30 ms
Packet loss	Below 1%	Above 1%
Round-trip latency	Below 150 ms	Above 200 ms

If a customer sits consistently in the "Problematic" column, voice quality will suffer on any platform, and the fix is on their network. Everything else (ports, firewall settings, NAT timeouts, QoS tagging) lives in the Network Requirements guide; the symptom sections below link to the relevant part of it when it matters.

Audio and call-quality symptoms

Choppy, robotic, or garbled audio

What it sounds like: Words are cutting in and out, voices sound distorted or underwater, audio breaks up.

Most likely causes, in order:

1. Packet loss. Audio packets aren't arriving. Check the Call Quality dashboard for packet loss above 1%.
2. Jitter. Packets arrive in bursts instead of evenly. Check for jitter above 30 ms.
3. Wi-Fi. Wi-Fi is the single biggest source of call-quality complaints. Wired Ethernet is always more reliable than wireless.
4. Network congestion. Another device on the same network is saturating the connection (large upload, video call, backup).

What to try:

1. Have the user switch from Wi-Fi to Ethernet for one test call, even if they have to plug into a router temporarily. If the call is clean on Ethernet, the problem is Wi-Fi.
2. On Wi-Fi, move closer to the access point and make sure the device is on 5 GHz, not 2.4 GHz.
3. Run a VoIP-grade network test from the affected location.
4. Pause any large uploads, cloud backups, or video calls and try again.
5. If the customer has QoS available on their router, enable it for voice traffic.

When to escalate: Network tests pass and MOS is still consistently below 3.5 across multiple users at the location.

One-way audio

What it sounds like: Caller A can hear caller B, but caller B can't hear caller A (or vice versa).

Most likely causes, in order:

1. Symmetric NAT or restrictive firewall on the customer's network. Outbound audio packets get out, return packets get blocked.
2. SIP ALG enabled on the customer's router. SIP ALG modifies SIP traffic in ways that often break the return media path.
3. Headset or mic-mute issue on the device. Easy to dismiss, but worth confirming first.

What to try:

1. Confirm the user's mic isn't muted, both physically and in software. Try a different headset.
2. On the customer's router, disable SIP ALG if it's enabled. The setting name varies by manufacturer; common labels: "SIP ALG", "SIP Helper", "SIP Transformation", "VoIP passthrough".
3. Confirm the customer's firewall allows UDP outbound and that there's no double NAT (router behind another router) on their network.
4. For WebRTC clients, the SDK uses TURN relay automatically to handle symmetric NAT, so this is rare. For SIP desk phones, NAT and SIP ALG are the usual suspects.

When to escalate: SIP ALG is off, firewall is permissive, mic and headset are confirmed good, and one-way audio persists.

Echo or feedback

What it sounds like: The user hears their own voice come back at them, sometimes with a delay.

Most likely causes:

1. Speakerphone too close to the mic. Acoustic feedback. Use a headset.
2. Two devices on the same call. Sometimes a user accidentally answers on both their desk phone and softphone.
3. Bluetooth headset glitch. Reconnect or pair fresh.

What to try:

1. Use a wired headset.
2. Make sure only one device is in the call.
3. Lower speakerphone volume.

Echo is almost always a device or environment issue, not a network or platform issue.

Dropped calls mid-conversation

What it sounds like: A call disconnects after some duration, sometimes consistently around the same time (30 seconds, 30 minutes, an hour).

Most likely causes:

1. ICE/media timeout for WebRTC clients. The media path failed to establish properly and the connection drops around the 30-second mark.
2. NAT translation timeout for SIP desk phones. The customer's router drops the NAT mapping after a period of inactivity.
3. Network failover at the ISP level. The customer's internet briefly switched paths and the call couldn't recover.
4. Wi-Fi roaming. The user moved between access points mid-call.

What to try:

1. Check whether the drops are consistent in timing. A drop at exactly 30 seconds for WebRTC users suggests a firewall is blocking UDP and the TURN-over-TCP fallback is blocked too, so no media path can be established. Verify the firewall config against Ports and destinations in the Network Requirements guide.
2. For desk phones, confirm the phone's SIP registration is healthy (most phones show a registration status on their display). If it re-registers frequently, the NAT timeout is too short. The DialStack-provided phones handle keep-alives correctly by default; if the customer brought their own phone, the keep-alive interval may need adjusting.
3. If drops correlate with the user moving around, suspect Wi-Fi roaming.

When to escalate: Drops are consistent across multiple users and devices, and network tests pass.

Calls fail to connect (fast busy, dead air, ring with no pickup)

What it sounds like: The customer dials and hears a fast busy tone, nothing at all (dead air), or normal ringback but the call never connects to a person.

Most likely causes:

1. Dial plan misconfiguration. The call is routing somewhere it shouldn't. Open the Dial Plans view in the admin portal and trace the route.
2. Number was ported away or not yet ported in. Check the number's status in the admin portal.
3. Carrier-side block. Less common, but the destination number is on a block list.
4. Outbound calling permissions. The user's role doesn't allow the type of call (international, premium rate).

What to try:

1. Have the customer try a different destination number. If it works, the problem is the original number.
2. Trace the call in the Call List (find the call by time, click into Call Detail). The status field tells you exactly where it ended.
3. Check the dial plan that handles the route.

Inbound calls don't ring

What it sounds like: Customer says people calling them get voicemail directly, or it just rings forever, or doesn't ring at all.

Most likely causes:

1. Dial plan or routing issue. The number is routing to voicemail, an inactive group, or a Voice App that's misconfigured.
2. Do Not Disturb is on for the user or the group.
3. Phones aren't registered. No active device to receive the call.
4. Number not assigned to a user, group, or dial plan.
5. NAT mapping pruned by the customer's router. The phone reports itself as registered, but the router silently dropped the NAT entry between keepalives, so the inbound call has nowhere to land. Common on enterprise firewalls and UTM appliances with aggressive UDP connection-tracking timeouts.

What to try:

1. Confirm the number is assigned and routed correctly in the admin portal.
2. Check that the receiving user or group has at least one registered device. The Call Logs will show whether the call attempted to ring a device.
3. Test by calling the number from an outside line.
4. If the phone shows registered but inbound calls still don't ring, suspect NAT pruning. Reboot the phone (which forces a fresh registration and a new NAT mapping) and immediately try the call again. If the call works right after a reboot but fails later, the customer's router is pruning the NAT entry more aggressively than the keepalive interval. See UDP connection tracking in the Network Requirements guide for the fix.

Voicemail not delivering

What it sounds like: Customer says voicemails come in but the notification, transcription, or email forward isn't arriving.

Most likely causes:

1. Email address on the user is wrong or notifications aren't enabled.
2. Email is being filtered as spam by the customer's email provider.
3. Notification settings turned off at the user level.

What to try:

1. Verify the email address on the user's profile.
2. Check the recipient's spam folder.
3. Send a test voicemail and confirm it appears in the user's voicemail box in the admin portal (which confirms the voicemail itself worked) before assuming the notification chain is broken.

Caller ID wrong or showing "unknown"

What it sounds like: Outbound calls show a wrong number, or inbound calls show "Unknown" instead of a name.

Most likely causes:

1. Outbound caller ID is set to the wrong number on the user or location. Check the user's settings.
2. CNAM registration. "Caller name" (CNAM) is a separate registration from the number itself and can take days to propagate after a number is added.
3. Receiving carrier doesn't look up CNAM (common on mobile networks). This is not something either you or DialStack can change.

What to try:

1. Confirm the outbound caller ID is set correctly on the user's profile in the admin portal. Each user can have a per-user outbound caller ID that overrides the account default; check that this is set to the number you expect.
2. For inbound "Unknown" calls, the calling party's CNAM may not be in any directory, which is normal.

Device and app symptoms

Desk phone won't boot or shows no display

1. Confirm the phone is getting power: PoE from the network switch, or a separate power adapter. The phone's power LED should be on.
2. Confirm the network cable is in the LAN port, not the PC port.
3. If the phone is using PoE, try a different switch port. Some switch ports are non-PoE.
4. Reboot the phone by unplugging it for 30 seconds, then plugging it back in.

Desk phone won't register (shows "no service" or similar)

1. Confirm the phone is on the network. Most phones display their assigned IP address on the status screen. If it's 0.0.0.0 or self-assigned, the phone isn't getting DHCP.
2. Confirm the customer's firewall allows the required ports.
3. Re-provision the phone from the admin portal. See Managing Devices for the re-provision flow.
4. Last resort: factory reset the phone, then re-provision. Per-vendor reset steps (Snom, Yealink, Poly) are in the Migrating Existing Phones guide.

Desk phone shows the wrong user or extension

The device is assigned to a different user than expected. Open the user's profile in the admin portal, reassign the device, and the phone will re-provision on its next check-in (usually within a few minutes; reboot the phone to force it).

Softphone or WebRTC client won't sign in

1. Confirm the user's credentials are correct.
2. Confirm the user's account is active in the admin portal.
3. Try in a different browser or on a different network to isolate whether it's a local issue.
4. For WebRTC specifically, the user's browser must allow microphone access. Chrome, Edge, and Firefox prompt the first time; if the user previously denied the prompt, the permission has to be reset in browser settings.

DECT handset won't pair or shows "no base"

1. Confirm the base station is online and registered.
2. Bring the handset within a few feet of the base.
3. Re-run the pairing process from the handset menu (varies by manufacturer; usually under Settings → Registration).
4. If the base shows the handset is registered but the handset still says "no base", reboot both.
5. If pairing still fails, factory reset the base station and let the handsets re-pair; per-vendor steps for the Snom M-series and Poly Rove bases are in the Migrating Existing Phones guide.

VoiceAI symptoms

DialStack's VoiceAI agent (a Voice App) is a configurable AI receptionist that answers calls, follows instructions, references an FAQ, and (when configured) looks up customers and books appointments via a webhook. Below are the common things that go wrong, and how to triage them.

Agent doesn't answer

1. Confirm the Voice App is wired into the dial plan that handles the affected number. Open the dial plan and look for a Voice App node on the path.
2. Confirm the Voice App is enabled and configured. An empty Instructions field or a missing greeting can cause the agent to fail to start.
3. Check whether the call is reaching the Voice App at all in the Call Logs. If the call ends before the Voice App node, the issue is upstream in the dial plan, not in the agent.

Agent hangs up early or seems confused

1. Review the agent's Instructions field. Vague or contradictory instructions are the most common cause of unexpected behavior.
2. Review the FAQ entries. The agent leans heavily on these for answers; if a customer asks something the FAQ contradicts, the agent will get confused.
3. Check call recordings or transcripts on the Call Detail page to see exactly what the caller said and how the agent responded. Most "the AI is broken" reports resolve into "the instructions or FAQ need a small edit."

Agent doesn't transfer to a person

The agent can perform a blind transfer to a person: it says a handoff sentence, then connects the caller to an extension or an outside phone number. What it cannot do yet is an attended (warm) transfer — speaking to the receiving person before handing the caller off. Attended transfer is on the DialStack roadmap.

If transfers aren't happening when they should:

1. Review the agent's Instructions. The agent transfers when its instructions tell it to; if they never mention when to transfer or who to transfer to, it won't. Spell out the trigger and the target, e.g. "If the caller asks for billing, transfer them to extension 101."
2. Confirm the transfer target is valid: an extension that exists on the account, or a full phone number. If the target user has no registered device, the transfer rings nothing — check device registration.
3. Check the transcript on the Call Detail page to see whether the agent attempted the transfer at all, then where the call went after it.

If callers should reach a human before the agent in some cases, handle that upstream in the dial plan instead: an IVR that offers "1 for our team, 2 to talk to our AI assistant", or a ring group that rings real people during business hours and falls back to the Voice App after hours.

Booking or scheduling integration isn't working

1. Confirm the scheduling webhook URL on the Voice App is correct and reachable.
2. Confirm the webhook secret matches the one configured on the customer's scheduling system.
3. The webhook is signed; the receiving system needs to verify the signature. If the customer's system isn't verifying correctly, requests will be rejected.
4. Check the customer-side webhook logs for any error responses sent back.

Transcription is missing or wrong

1. Transcription happens after the call ends. Wait a minute or two and reload the Call Detail page.
2. Accuracy depends on audio quality. If the underlying call had high packet loss or low MOS, transcription quality suffers. Check the Quality Metrics on the same Call Detail page.
3. Background noise, multiple talkers, and accents all reduce accuracy. This is a limit of speech-to-text in general, not a DialStack-specific defect.

Customer network diagnostics

When the Call Quality dashboard points at the customer's network, confirm it from their side using the validation tests and firewall checks in the Network Requirements guide. Run them from a device on the same connection as the affected phones (wired if the phones are wired, the same Wi-Fi if they're wireless):

• Run the VoIP-grade network test and continuous ping (the Cloudflare speed test plus a ping over a few minutes), then compare the result against the thresholds above.
• Confirm SIP ALG is disabled on the router.
• Rule out double NAT.

If the tests pass but quality is still poor, that's an escalation (see Information to collect before escalating). The guide also covers Wi-Fi, PoE, DHCP, and QoS specifics if you need to go deeper.

Information to collect before escalating

When you need to escalate an issue to DialStack, the speed of resolution depends almost entirely on the data you send with the escalation. Collect the following before you write:

• Customer account name in the admin portal.
• Affected location, if more than one.
• Affected users or phone numbers, with caller and called numbers for any specific failed calls.
• Exact timestamp of the failed call, with timezone (e.g., "2026-05-28 14:32 PT").
• Call ID from the Call Detail page if you can pull it.
• Symptom, in the customer's words: "calls cut out", "people can't hear me", "ring with no answer".
• Reproducibility: one-off, intermittent, always.
• MOS / jitter / packet loss from the Call Quality dashboard for the affected window.
• Network test results if you ran one.
• What you've already tried so DialStack doesn't suggest the same things back.
• Screenshots of any error messages or unexpected behavior.

An escalation with this in the first message gets resolved in one round of back-and-forth. One without it usually takes three or four.

Where to escalate: send it through your shared Slack channel with DialStack, or to your DialStack contact if you don't have a channel set up yet.

Glossary

• MOS (Mean Opinion Score): A 1 to 5 rating of perceived voice quality. Above 4.0 is good.
• Jitter: Variation in the arrival time of audio packets. High jitter makes audio choppy.
• Packet loss: Percentage of audio packets that fail to arrive. Anything above 1% is noticeable.
• Latency / RTT (round-trip time): How long a packet takes to travel from one end to the other and back. High latency causes conversational delays.
• Codec: The format used to encode voice. DialStack uses Opus and other high-definition voice codecs wherever both endpoints support them, on supported physical desk phones and even on PSTN legs when the upstream carrier can negotiate HD. G.711 is the fallback when an HD codec isn't available end-to-end.
• SIP: The signalling protocol used by desk phones to register and place calls.
• RTP: The protocol used to carry the actual audio.
• SIP ALG: A router feature that inspects and modifies SIP traffic. Usually does more harm than good with hosted VoIP. Turn it off.
• NAT (Network Address Translation): The mechanism a router uses to share one public IP across many private devices.
• STUN / TURN: Servers that help voice clients work through NAT and restrictive firewalls.
• DSCP / QoS: Tagging that lets a router prioritize voice traffic over other traffic.
• PoE (Power over Ethernet): A way to power a desk phone through the same network cable that carries its data.
• Voice App: DialStack's name for an AI agent configured to handle calls.

Related

• Admin Guide
• Network Requirements
• Call Quality dashboard documentation
• Dial Plans
• Managing Devices
• Voice Apps
• WebRTC Network & Troubleshooting
• Changelog