How to Troubleshoot and Diagnose NetSapiens SIP Flows: A Field Guide for MSPs

Every MSP running a hosted PBX eventually gets the call: "My phones are ringing but no one can hear me," or "Outbound to one specific area code fails every time." If your platform is built on Viirtue, NetSapiens is the UCaaS backend handling the SIP signaling for that call - and the answer is buried inside the NetSapiens SIP flows behind the Viirtue portal. The trace is there. The question is whether you know how to read it.

This guide walks through how SIP signaling moves through the NetSapiens UCaaS core, how to pull and interpret traces inside the Viirtue portal, and how to map common symptoms to specific fixes. It is written for engineers who already know what a SIP INVITE looks like but want a faster, more repeatable diagnostic process.

TL;DR

What Are NetSapiens SIP Flows?

NetSapiens SIP flows are the sequences of SIP (Session Initiation Protocol) messages exchanged between a SIP endpoint - a desk phone, softphone, or ATA - the NetSapiens UCaaS core powering the Viirtue platform, and any upstream or downstream peers (SBCs, carriers, PSTN gateways) to establish, modify, or terminate a voice or video session.

A flow is not a single message. It is the full conversation, identified by a shared Call-ID header, that begins with an INVITE and ends with a BYE or a failure response. When engineers talk about "diagnosing a SIP flow," they mean reading that full conversation to find where it broke.

A SIP flow is the logical sequence of signaling events for a call. A SIP trace is the captured log of those events, with timestamps and full headers, that you actually read during diagnosis. Inside the Viirtue platform, traces are stored by Call-ID and accessible through the portal or via PCAP export.

Why SIP Flow Literacy Matters in 2026

NetSapiens is the carrier-grade UCaaS backend that powers Viirtue's white-label VoIP partner platform. It is the SIP signaling and media engine sitting underneath the Viirtue portal, ViiBE billing system, AI voice agents, and white-label tooling that resellers actually interact with. Understanding how SIP flows move through that core is the difference between resolving a customer ticket in minutes and chasing it through the night.

At the same time, the FCC's STIR/SHAKEN enforcement framework has changed the failure landscape. Calls signed with B-level or C-level attestation are now routinely rejected by terminating carriers, which means a perfectly healthy SIP flow on your side can still fail with a 4xx response from upstream. The IETF specification for SIP (RFC 3261) has not changed, but the operational reality around it has.

For MSPs and telecom resellers, that translates to one practical truth: engineers who can read a trace in under 60 seconds are the difference between a 15-minute ticket and a 4-hour outage.

The Anatomy of a Healthy SIP Flow

Before you can diagnose a broken flow, you need a clear mental model of a working one. The full message exchange is defined in IETF RFC 3261, but here is the standard sequence for an outbound PSTN call through a NetSapiens deployment:

SIP Phone (192.168.x)  --INVITE-->  NetSapiens UCaaS Core + SBC  --INVITE-->  Carrier (Bandwidth, Inteliquent, Peerless)
                       <--100/180--                                <--100/180--
                       <--200 OK---                                <--200 OK---
                       --ACK------->                               --ACK------->
                       <------------ RTP (audio) ----------------------------------------->
                       --BYE/200-->                                --BYE/200-->

The expected sequence:

1. INVITE from the phone to NetSapiens with SDP offer (codecs, RTP port, IP)
2. 100 Trying from NetSapiens, acknowledging receipt
3. NetSapiens applies the dial plan, translates the destination, and forwards the INVITE to the carrier
4. 180 Ringing (or 183 Session Progress) flows back
5. 200 OK with SDP answer when the far end picks up
6. ACK completes the three-way handshake
7. RTP media flows directly between endpoints (or via SBC if media anchoring is enabled)
8. BYE / 200 OK tears down the session

When any one of those messages is missing, malformed, or returns a 4xx or 5xx, you have a problem to diagnose. The sequence above is your baseline - anything that deviates from it is a data point.

Where to Pull SIP Traces

Because NetSapiens is the UCaaS backend powering the Viirtue platform, SIP traces are surfaced through the Viirtue portal with the underlying NetSapiens trace data in a reseller-friendly view. Knowing which view to use saves meaningful time on every ticket.

1. Viirtue Portal - Call History

The fastest path. Navigate to Call History for the affected user or domain inside the Viirtue portal, find the call by timestamp, and click the trace icon. You get a chronological list of every SIP message with full headers, drawn directly from the NetSapiens core.

2. Domain-Level SIP Trace

For issues affecting multiple users - a carrier outage, dial plan corruption, or a class-of-service misconfiguration - pull the trace at the domain level. This surfaces patterns that user-level traces hide, particularly when the same failure appears across different endpoints.

3. PCAP Export for Carrier Disputes

When you need to send evidence to a carrier or upstream peer, export the full PCAP from the platform. Open it in Wireshark, filter by sip and rtp, and you have a timestamped, court-ready record the carrier cannot argue with.

4. Backend CLI (Platform Engineering Access)

# Tail signaling log for a specific Call-ID
tail -f /var/log/sipsg.log | grep "Call-ID: abc123@..."

# Filter active SIP dialogs
ndp_request sip_dialogs

The Call-ID is in the SIP message headers, usually the fourth or fifth header line after the request URI, formatted as Call-ID: <unique-string>@<host>. The platform uses this string to stitch together every hop of the call - always copy it before you start digging.

The 7 Most Common SIP Flow Failures (with Real Examples)

1. One-Way Audio (Caller Hears Callee, Callee Hears Silence)

This is the single most common ticket in hosted voice, and it is almost never a SIP signaling issue. The INVITE, 200 OK, and ACK all complete cleanly. The call connects. But media flows in one direction only.

The SDP fingerprint in the trace:

v=0
o=- 1234567890 1234567890 IN IP4 10.0.0.5     <-- Private IP leaked into SDP
s=-
c=IN IP4 10.0.0.5                              <-- Same private IP in connection field
t=0 0
m=audio 16384 RTP/AVP 0 8 101

The phone is behind NAT and advertised its private IP in the SDP. The far end tries to send RTP to 10.0.0.5, the packets have nowhere to go, and you get one-way audio. The SIP flow looks perfectly healthy because signaling is fine - only RTP is broken.

Fix: Enable SBC media anchoring so the platform rewrites SDP using the public source IP. For Polycom and Yealink endpoints, set the keep-alive interval to 25 seconds to hold the NAT pinhole open. Run the Viirtue VoIP Qualifier on the customer's network before deployment to detect symmetric NAT and SIP ALG interference before the first phone ships.

2. 403 Forbidden on Outbound Calls

Symptom: User dials, hears a fast busy immediately. Ticket says calls fail right away.

INVITE sip:+15551234567@core.example.net SIP/2.0
...
SIP/2.0 403 Forbidden
Reason: Q.850;cause=21;text="Call Rejected"

Likely causes, in order of how often they appear:

• The user's class of service does not permit that destination (international, premium rate, toll-free)
• Carrier-side rejection because the calling number is not on the carrier's approved DID list
• STIR/SHAKEN attestation failure - the call is signed as C-level and rejected by the terminating carrier
• Dial plan strips a leading digit incorrectly, producing an invalid E.164 number

Diagnostic order: Check the user's permissions first (30 seconds in the portal), then verify the dial plan translation, then escalate to the carrier with the PCAP.

3. 488 Not Acceptable Here (Codec Mismatch)

INVITE sip:bob@example.net SIP/2.0
...
m=audio 16384 RTP/AVP 9                        <-- Phone only offers G.722

SIP/2.0 488 Not Acceptable Here
Warning: 304 core "Incompatible media format"

The originating phone offered only G.722 (codec 9), but the destination only supports G.711 (codec 0 or 8). NetSapiens cannot transcode by default in every deployment configuration, so the call fails rather than proceeding with degraded quality.

Fix: Enable transcoding at the SBC, or push a phone configuration that includes G.711 in the codec list alongside G.722.

4. 408 Request Timeout

INVITE sip:+15551234567@carrier.example.com SIP/2.0
...
(no response for 32 seconds)
SIP/2.0 408 Request Timeout

The carrier is not responding. This is almost always upstream. Check carrier status pages, verify your IP allowlist on their side, and confirm whether your outbound IP address changed after a maintenance window or failover event.

5. 503 Service Unavailable

SIP/2.0 503 Service Unavailable
Retry-After: 60
Reason: Q.850;cause=41;text="Temporary Failure"

Carrier overload, or your SIP trunk has hit its concurrent call limit. Check carrier capacity under the Trunks section of NetSapiens. Bursting carriers will throw 503 responses long before they send a notification explaining why.

6. Registration Loop (User Keeps Going Offline)

Symptom: Phone shows "Registered" then "Not Registered" cycling every few minutes.

REGISTER sip:core.example.net SIP/2.0
Contact: <sip:bob@10.0.0.5:5060>;expires=3600

SIP/2.0 200 OK
Expires: 60                                    <-- Server overrode to 60 seconds

The phone requested a one-hour registration. NetSapiens or the SBC overrode it to 60 seconds. The phone is not re-registering quickly enough, the NAT pinhole closes between cycles, and the endpoint drops.

Fix: Align the phone's re-register interval to under 60 seconds, or increase the server's accepted registration expiry on the domain settings. The Viirtue VoIP Qualifier will surface NAT type and any symmetric NAT conditions that make this worse.

7. Ghost Calls / Phantom Rings

Symptom: Phone rings, user picks up, no one is there. Caller ID shows "1000" or a random extension.

This is a public-facing SIP port being probed by attackers. Your phones are exposed on TCP/UDP 5060 to the open internet, and bots are sending unauthenticated INVITEs. This is not a platform bug - it is a network exposure problem.

Fix: Restrict the phone's signaling port to the NetSapiens SBC IP ranges only. Disable direct SIP where possible and rotate to a non-standard signaling port on the LAN side. This issue will not appear in the Viirtue portal trace because the INVITE never reaches the platform - it is hitting the phone directly.

Reading a NetSapiens SIP Trace Line by Line

Here is an annotated trace from a successful outbound call. Reading this structure fluently is the single highest-leverage diagnostic skill for MSPs running a hosted VoIP practice.

[14:22:01.103] PHONE -> CORE
INVITE sip:+18005551212@nscore.viirtue.com SIP/2.0
Via: SIP/2.0/UDP 10.10.1.50:5060;branch=z9hG4bK-abc123
From: "Bob Sales" <sip:1001@viirtue.com>;tag=xyz789
To: <sip:+18005551212@viirtue.com>
Call-ID: 89f3a1b2-c4d5-6e7f@10.10.1.50         <-- Track this everywhere
CSeq: 1 INVITE
Contact: <sip:1001@10.10.1.50:5060>
Max-Forwards: 70
User-Agent: PolycomVVX-VVX_450-UA/6.4.4.7956
Content-Type: application/sdp
Content-Length: 281

What to check first:

• From and To lines confirm who is calling whom from the device's perspective
• Call-ID is your tracking key for the entire diagnosis - copy it immediately
• User-Agent identifies the endpoint vendor and firmware version, which is critical for known-issue lookups
• Contact tells you where the phone expects response messages to be delivered

Continuing through the same call:

[14:22:01.105] CORE -> PHONE
SIP/2.0 100 Trying
Via: SIP/2.0/UDP 10.10.1.50:5060;branch=z9hG4bK-abc123
Call-ID: 89f3a1b2-c4d5-6e7f@10.10.1.50
CSeq: 1 INVITE

[14:22:01.180] CORE -> CARRIER
INVITE sip:+18005551212@carrier-sbc.bandwidth.com SIP/2.0
...
Call-ID: 89f3a1b2-c4d5-6e7f@nscore.viirtue.com  <-- Call-ID persists on this leg
...
P-Asserted-Identity: <sip:+13055551001@viirtue.com>
Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6...        <-- STIR/SHAKEN signature

The Identity header is the STIR/SHAKEN attestation (defined in IETF RFC 8224). If a downstream carrier rejects the call with a 4xx and a verstat issue, this is the field they are validating. A missing or malformed Identity header is a fast path to carrier rejection.

[14:22:01.450] CARRIER -> CORE
SIP/2.0 200 OK
...
Content-Type: application/sdp

v=0
o=- 998877 998877 IN IP4 198.51.100.4
s=-
c=IN IP4 198.51.100.4                            <-- Public IP, clean
m=audio 27842 RTP/AVP 0 101

200 OK with a clean SDP. RTP will flow to 198.51.100.4:27842. Both the c= line and the m=audio port show public, routable values. From here, ACK closes the handshake and media starts. This call will work.

The fastest diagnostic method: Always start by isolating the Call-ID. Then scan vertically for any non-2xx response codes, looking specifically at the first 4xx or 5xx in the sequence. That first failure is almost always the root cause - everything after it is downstream noise from the original break.

Troubleshooting Matrix: Symptom to Cause to Fix

Use this matrix as your first-pass reference on any inbound ticket. Map the symptom to the most likely cause, run the first diagnostic step, and apply the fix. If the first path does not resolve it, move to the next row that matches.

Scroll to see full table on mobile

Why Viirtue Resellers Diagnose Faster

NetSapiens is a powerful carrier-grade UCaaS core. On its own, it gives you signaling and media. The operational layer - billing, branded portals, reseller hierarchy, AI voice agents, compliance tooling - is left to whoever deploys it. Most MSPs do not have a senior SIP engineer on staff to build and maintain that layer themselves.

Viirtue's hosted VoIP platform sits on top of the NetSapiens UCaaS backend and fills in the operational gaps that matter for partners at scale:

Integrated SIP trace correlation. Every call inside the Viirtue portal has its trace, billing record, and CDR cross-linked on the same record. You do not jump between three systems to find out why a customer was billed for a failed call or to pull evidence for a carrier dispute.

AI voice agents native to the PBX. Unlike stitched-together stacks built on third-party voice agent platforms with no native SIP infrastructure, Viirtue's AI voice agents share the same SIP infrastructure as your hosted phones. Traces, attestation, and billing all live in one place. When an AI agent call fails, you read the same SIP flow you would read for a human user.

Built-in billing automation. ViiBE handles usage rating, telecom tax calculation, and invoicing automatically. Carrier disputes get resolved against your actual CDR data, not a CSV export and a spreadsheet built the night before a carrier call.

Compliance handled at the platform level. STIR/SHAKEN signing, telecom tax calculation, and regulatory fees are built into the platform. When a carrier rejects on attestation grounds, you have audit trails ready without manual data assembly.

Reseller-first economics. Unlike RingCentral, 8x8, Dialpad, or Zoom Phone - all of which treat partners as a sales channel rather than the operator - Viirtue's white-label partner program gives resellers full control over the platform, pricing, and brand. You own the customer relationship. Viirtue handles the infrastructure.

The result: when a SIP flow breaks at 2 AM, your tier-1 tech can pull the trace, read it, and resolve the ticket without paging a senior engineer. That is the operational difference between a platform built for resellers and one that happens to have a partner tier.

NetSapiens SIP Flow Troubleshooting and the Partner Opportunity

SIP flows are not magic. They are conversations, written down, that always tell you what went wrong if you can read them. The MSPs who resolve tickets fastest are the ones who treat SIP trace literacy as a first-tier support skill rather than an arcane specialty reserved for the senior engineer on call.

The diagnostic process is repeatable: isolate the Call-ID, scan for the first non-2xx response, inspect the SDP for private IPs or codec mismatches, and cross-reference with the CDR. That sequence covers the overwhelming majority of NetSapiens SIP flow failures in the field. Before any of that, run the Viirtue VoIP Qualifier on the customer's network to rule out the bandwidth, jitter, NAT, and SIP ALG conditions that cause the majority of tickets before they ever show up as a SIP failure.

Viirtue's platform layers correlated traces, ViiBE billing automation, AI voice agents, and compliance tooling on top of the NetSapiens UCaaS backend, so the diagnostic and operational work your team does happens in one place rather than across three disconnected systems. If you are evaluating what a full-stack hosted VoIP infrastructure actually looks like for a white-label practice, Viirtue's partner program is built for MSPs and IT providers who want margin ownership and operational clarity, not referral fees and platform dependency.