These are the recurring gotchas and good habits for running CCaaS on a NetSapiens site, collected from across the individual NetSapiens in CCaaS topics.

Naming and Scoping the API User

The API user created for CCaaS to connect with — see Target Platform — should be named something recognizable like Xima LB or Xima CCaaS, so no one mistakes it for a live agent and deletes it. Its scope needs to be Office Manager or higher, or the connection won't work.

Save Virtual Handset Credentials Early

Once a virtual handset's Domain, Outbound Proxy, Username, and Password become visible on its phone configuration screen, it's worth saving that information right away — that screen can be easy to lose track of, and the same details are needed throughout the rest of setup. See SIP Extensions.

Registering an Extension Restarts CCaaS

Saving a SIP extension restarts CCaaS's primary and helper nodes. This should be scheduled outside business hours for a live customer, not done in the middle of the day. See SIP Extensions.

SIP ALG

SIP ALG (Session Initiation Protocol Application Layer Gateway) is a feature built into many routers and firewalls that inspects and rewrites SIP traffic to help it traverse NAT. In practice, it frequently conflicts with how CCaaS and SIP-based endpoints already handle NAT, making it a common source of hard-to-diagnose call issues.

⚠️
Disable SIP ALG
SIP ALG should be disabled on the router or firewall serving CCaaS phones and endpoints. Leaving it enabled is a common source of hard-to-diagnose call issues.

Symptom	Cause
Call dropping mid-conversation	SIP ALG misroutes or times out the RTP media stream
One-way or no audio	SIP ALG alters SIP headers that carry media routing information
Registration failures	SIP ALG interferes with the SIP registration handshake
Devices stuck in reboot loops	A device that cannot register correctly may continuously restart
Codec mismatches or poor audio quality	SIP ALG alters codec negotiation data in the SIP payload
SIP trunk authentication failures	SIP ALG modifies authentication data within SIP packets

A router or firewall's admin interface usually has a NAT, Firewall, or Application Layer Gateway setting named SIP ALG that can be disabled directly.

📘
ISP-Managed Equipment
Some ISPs enable SIP ALG by default on equipment they manage. If the router or firewall isn't directly accessible, the ISP or network admin responsible for the site can confirm or disable SIP ALG on request.

Firewall and QoS Configuration

Beyond disabling SIP ALG, a few additional firewall and quality-of-service settings help ensure reliable call quality:

Setting	Recommendation
WAN load balancing	If multiple WAN connections are in use, phones should fail over between circuits rather than load-balance across them. CCaaS registers a phone's IP address, so a mid-session IP change can prevent the phone from downloading configuration and directory data.
Traffic prioritization	A firewall rule should prioritize traffic to and from the phone system's core and provisioning servers.
SIP signaling ports	UDP/TCP 5060 (or 5061 for secure SIP) should be open, per the network requirements provided for the deployment.
RTP media ports	The RTP port range specified in the deployment's network requirements should be open; RTP traffic doesn't usually require special firewall handling beyond this.
DSCP marking	Voice traffic should be marked for prioritized handling — commonly EF46 for RTP and CS3 for SIP signaling — with switches connected to phones configured to trust these markings.

📘
Server and Port Details Vary by Deployment
The exact FQDNs, IP addresses, and port ranges to whitelist depend on the specific phone system deployment and are provided in that deployment's network requirements documentation, rather than a fixed list.

Set Aside a Testing DID Before Connecting

Before starting the Target Platform connection, it helps to have a DID already routed to the CCaaS virtual handset set aside, so inbound call routing can be tested as soon as the connection is complete. See Target Platform.

The Trailing Slash Matters When Tagging a Call for a Skill

Whether a DID or an Auto Attendant menu option is sending a call into a skill, the Caller ID Prefix needs a trailing slash to be recognized as a routing tag — without it, the call won't match anything in CCaaS. A default skill should also always be configured, since a call that matches nothing disconnects immediately. See Call Routing in CCaaS.

Missing Caller ID Is the Usual Cause of Outbound Failures

If outbound calls or Queue Callback Assist calls aren't connecting, the first thing to check is whether the user placing the call has a Caller ID set on the NetSapiens side. See Outbound Calls and Callback Assist Not Connecting.

SNAPmobile Alone Doesn't Show Contact Center Context

An agent using SNAPmobile only sees the internal extension a call arrives on — not the caller's information or which skill the call came through. CCAC is still needed for that context. See SNAPmobile.

International Calling Doesn't Apply Retroactively

Enabling international calling at the domain level only affects new users created afterward — existing users still need to be updated individually. See International Calling.