docs: add Network Allowlist page (enterprise firewall/proxy domains)

[raj-dubey1]

Adds a single Network Allowlist page so enterprise customers can let CometChat through a corporate firewall, proxy or VPN without hunting for domains across the docs. It also closes ENG-39686 (ports split by client type).

What

New page fundamentals/network-allowlist.mdx, under Chat & Messaging → Platform:

• Domains: CometChat's own hosts are on four domains. cometchat.io, cc-cluster-2.io and cc-edge-2.io carry the runtime, and cometchat.com carries the Dashboard and website. The JavaScript Calls SDK also uses a few third-party hosts, which are listed separately.

• Quickest option: allow the four wildcards plus the apex domains, with a warning that some hosts are two or three labels deep, so the rules need "any depth".

• Per-service host list for teams that can't use wildcards:

  • runtime: App ID hosts on all three families; AI Agent Service and Moderation on cometchat.io only,
  • extensions (<extension>-<region>.<family>),
  • calling: signalling <appId>.xmpp.rtcv5-<region>.cometchat.io and TURN relay turn.rtcv5-<region>.cometchat.io, both on TCP 443. Media servers are reached by IP, with TURN as the fallback. Also rtc-<region>.cometchat.io, the call screen for the older calling built into the Chat SDKs,
  • media, CDN, UI Kit and sample-app assets, metrics, Visual Chat Builder,
  • Dashboard and tooling, including the optional api-explorer.cometchat.com and mcp.cometchat.com.

  The page says only the wildcards are guaranteed to stay complete.

• Ports, split by client type:

  Client	Ports
  All current SDKs and UI Kits: JavaScript, React Native, Ionic and Flutter SDKs; native iOS and Android SDKs v3.0 and later; Widget; all UI Kits	TCP 443 only (WSS to <appId>.websocket-<region>.cometchat.io)
  Native iOS and Android SDK v2.x (Android 2.4.x and earlier, iOS 2.4.2 and earlier)	TCP 443, plus 5222 and 7443 to <appId>.ws-<region>.cometchat.io
  REST API (your servers)	TCP 443
  Voice and video	Signalling TCP 443; media UDP 10000–20000, with TCP 443 TURN fallback

• Webhooks (inbound): the one inbound exception. Secure the endpoint with Basic Auth, since source IPs aren't published.

• Also covered: push notifications (Google and Apple domains), build and CI hosts (including library.cometchat.io for iOS Swift Package Manager), and domain-not-IP guidance.

Also changed

• rest-api/chat-apis.mdx: links to the page from Data Center Hosting.
• sdk/javascript/troubleshooting.mdx: the "WebSocket fails" row links to the Ports section.
• docs.json: the nav entry. It also removes the duplicated User-Roles and Guides groups (fundamentals/user-roles-and-permissions and fundamentals/user-auth were listed twice); both pages stay in the nav once.

How the hosts were checked

• DNS: every host resolves against 8.8.8.8. App ID hosts use wildcard DNS, so a pattern was only kept if it resolves for any App ID. Patterns that never resolve were removed: cdn.cc-*, <appId>.ai-agent-service-*.cc-* and <appId>.rule-*.
• Calling: a live two-person call with @cometchat/calls-sdk-javascript 5.0.6. Its only WebSocket was wss://<appId>.xmpp.rtcv5-us.cometchat.io/xmpp-websocket, its ICE server was turns:turn.rtcv5-us.cometchat.io:443, and media connected through a relay. Both hosts resolve for us, eu and in.
• Chat connection: the /v3.0/me app settings return CHAT_HOST_APP_SPECIFIC: <appId>.websocket-<region>.cometchat.io and CHAT_WSS_PORT: 443.
• SDK history behind the 5222/7443 cut-off:
  • SDKs from v3.0 onward: iOS CometChatPro 3.x and CometChatSDK 4.x read the host and port from those settings and use a WebSocket library (Starscream). Android SDKs 3.0.0 through 5.0.7 depend only on OkHttp.
  • v2.x: these used raw XMPP. iOS 2.4.2 embeds XMPPFramework, and Android 2.4.x depends on Smack (smack-tcp).
  • The host: only <appId>.ws-<region>.cometchat.io has 5222 and 7443 open.
• Flutter: Flutter SDK v4 wraps native SDKs from v3.0 onward (Android 5.0.1, iOS 4.1.3), so it's 443 only. Flutter SDK v5 has its own WSS client on 443.
• Dashboard: the production Dashboard's JavaScript uses apimgmt.cc-cluster-2.io, campaigns.cc-cluster-2.io, api.cometchat.com (legacy API) and app-beta.cometchat.com, and loads widget-js.cometchat.io for Widget assets.
• Extensions: the JS SDK builds https://<extension>-<region>.<domain>/, with no App ID.

Safety

• One new page, one nav entry and two cross-links. The only removals are the duplicate nav groups. The page has never been live, so no redirects are needed.
• mint validate shows only the warnings main already has, and every link and anchor resolves.

Note for the Calls team

The page lists cdn.cometchat.io only for the background-blur model files. JavaScript Calls SDK 5.0.6 still loads them from cdn.cometchat-staging.com, where they return 200, while cdn.cometchat.io returns 403 for them today. The fix ships in the next Calls SDK release; until then, blur on 5.0.6 depends on the staging host, which the page intentionally doesn't list.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgVCxHs3h8m72GXvC8HaV1

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Oct 6, 2026, 12:10 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[raj-dubey1]

Updated for ENG-39686, as Ketan asked on the ticket (it replaces the closed #546).

Ports is now split by client type (network-allowlist.mdx):

Client	Outbound ports
Browser: JavaScript SDK, Widget, web UI Kits	TCP 443 only (realtime is WSS on 443)
Native iOS and Android	TCP 443, 5222, 7443
REST API	TCP 443
Voice and video media	UDP 10000–20000, TCP 443 fallback

Other changes on the page:

• A new note says browsers can't use or test 5222 and 7443, so browser-based customers should check 443 and WebSocket upgrades instead.
• The warning used to say "realtime chat and calling need more than port 443", which contradicted the browser row. It's now about proxies blocking WSS upgrades and firewalls blocking UDP.
• TCP 80 is no longer listed, per the ticket's split.

Troubleshooting: the "WebSocket fails" row in sdk/javascript/troubleshooting.mdx now links to Network Allowlist → Ports.

Checks: mint validate shows the same warnings as main, and none are in these files.

This adds a commit after the existing approval, so it needs a quick re-review.

[ketanyekale]

Re-reviewed after 265fbce3. The Ports split is good and covers ENG-39686: ports by client type, the note that browsers can't use or test 5222/7443, and the troubleshooting link to /network-allowlist#ports. Nav, redirects and internal links all check out.

Two content issues are still open, so I'm not approving yet.

Should fix before merge

1. "No inbound connections" is wrong for webhooks (network-allowlist.mdx L11, L174). CometChat sends requests to the customer's webhook URL, so teams that filter inbound traffic need to allow that. Please add a webhook/callback exception, with source IPs available on request.

2. The per-host list says it covers "every individual host" (L57) but misses some.

   • Dashboard: apimgmt.cc-cluster-2.io is the production dashboard backend; the page lists only apimgmt.cometchat.io (L114). Also missing are campaigns.cc-cluster-2.io, api.cometchat.com and app-beta.cometchat.com.
   • End users: widget-js.cometchat.io, whiteboard-<region>.cometchat.io and document.cometchat.io.
   • Extensions also appear on extensions-<region>.cc-cluster-2.io, which contradicts "Runtime — cometchat.io only" (L82–87).

   The wildcard option covers all of these, so only teams allowlisting host by host are affected.

Nits

• L28–29 says cc-cluster-2.io and cc-edge-2.io carry the "same services as above", but later sections list extensions, media and legacy WebSockets as cometchat.io-only, and metrics isn't on cc-cluster-2.io.
• L52: <appId>.api-<region>.cometchat.io is two labels under the apex, not three. The *.*.cometchat.io advice is still right.
• L89, L109, L119 use &; every other page uses a plain &.
• The Ports table doesn't name React Native, Flutter or Ionic, so those readers can't tell which row applies.
• TCP 80 is no longer listed here, but the Help Center whitelisting article still lists it. That article needs the same split so the two agree.
• The PR description still describes a Developer Tools placement and a two-domain wildcard; the page is under Platform with four domain families.
• The docs.json change also removes the duplicated User-Roles and Guides groups. That's safe (both pages stay in nav) but worth a line in the description.
• The branch is 70 commits behind main.

[raj-dubey1]

Thanks for the re-review. Everything below is in a67a6406, along with a merge of main; the branch was 70 commits behind. I checked every point against DNS, the SDKs or the production Dashboard before changing it.

1. Inbound claim: fixed. A new Webhooks (inbound) section says CometChat POSTs to your webhook URL, so that server must accept inbound HTTPS. Source IPs aren't published, so the section recommends the webhook's Basic Auth. The intro (L11) and Notes (L195) now point there instead of saying there's no inbound traffic.

2. Per-host list: fixed, with two corrections.

• Added, each confirmed in DNS and in the live Dashboard bundle:
  • apimgmt.cc-cluster-2.io (the Dashboard's customerDomain), with the other two families alongside it
  • campaigns.* on all three families
  • api.cometchat.com (legacyDomain v1.8)
  • app-beta.cometchat.com
  • widget-js.cometchat.io (Widget assets, so it's listed under runtime, not the Dashboard)
• Extensions: the old <appId>.extensions-<region>.cometchat.io pattern was wrong, and doesn't resolve for a real App ID. The JS SDK builds https://<extension>-<region>.<domain>/, and those hosts exist on all three families. The page now documents <extension>-<region>.<family>, with polls-, reactions-, stickers-, whiteboard-, document- and extensions- as examples.
• Whiteboard and document: document.cometchat.io doesn't resolve. The real hosts are document-<region>.<family> and whiteboard-<region>.<family>, both aliases of that region's extensions host, and both are covered by the pattern above.
• "Every individual host" now says only the wildcards are guaranteed to stay complete.

Nits: all fixed.

• "same services as above" now reads "most runtime services; see the per-service list".
• Two labels, not three.
• & is now &.
• The PR description is rewritten: it now covers the current nav location, the four domain families and the port split.

React Native, Flutter and Ionic: they go in the 443 row, not the native row. Their SDKs are WebSocket-based: the RN and Ionic packages are pure JS, and Flutter v5 is pure Dart using web_socket_channel. All of them connect over WSS on the same chatWSSPort app setting as the JS SDK, and none contains 5222 or 7443. Their UI Kits are named in the row too. A sentence explains why they're there even though they run on iOS and Android. The 5222/7443 note now says those ports are only for the native iOS and Android SDKs.

Help Center article: not in this repo. It needs someone with Help Center access to apply the same split and drop TCP 80. Suggested text:

Ports. Browsers and the JavaScript, React Native, Ionic and Flutter SDKs: TCP 443 only (realtime is WebSocket over HTTPS). Native iOS and Android SDKs: TCP 443, 5222 and 7443. Voice and video: UDP 10000–20000, with TCP 443 fallback. Browser-based apps can't use or test 5222 or 7443. Full list: https://www.cometchat.com/docs/network-allowlist#ports

Needs a maintainer to confirm. I didn't change these, but DNS doesn't back them for our dev app (16809324b41531513):

• <appId>.ai-agent-service-<region> resolves only on cometchat.io, not on cc-cluster-2.io or cc-edge-2.io.
• <appId>.rule-<region> (Moderation) doesn't resolve on any family.
• cdn.cc-cluster-2.io doesn't resolve.

These may be provisioned per app or per feature, so they need confirming against infra before the page claims them.

Checks: mint validate shows only the warnings main already has, and every link and anchor on the page resolves.

[raj-dubey1]

Added in fbc47ce7: the hosts that end users' devices fetch at runtime, in a new section, UI Kit, calling and sample app assets. I found each one in the shipped packages and sample apps, and each returns HTTP 200:

Host	Loads	Found in
assets.cc-cluster-2.io	Call and message sounds (/uikits/static/audio/*.wav), and the web sample apps' sampledata.json	@cometchat/chat-uikit-react 7.2.3 and chat-uikit-angular 5.2.1; the React and Angular sample apps
assets.cometchat.io	Mobile sample apps' sampledata.json and sample-user avatars	Android, iOS and Flutter sample apps
data-<region>.cometchat.io	Sample-user avatars	React and Angular sample apps
cdn.cometchat.io	Virtual backgrounds	@cometchat/calls-sdk-javascript 5.0.6
cdn.cometchat-staging.com	Background-blur model files (tflite.wasm, tflite-simd.wasm, selfie_segmentation_landscape.tflite)	@cometchat/calls-sdk-javascript 5.0.6
fonts.googleapis.com, fonts.gstatic.com	Roboto for the call screen	@cometchat/calls-sdk-javascript 5.0.6

Other changes:

• The Dashboard table's assets.cometchat.io row now says end users need it too.
• The wildcard section no longer says the four wildcards are enough. It now names the three hosts outside CometChat's domains.
• The CDN list keeps cdn.cc-cluster-2.io and cdn.cc-edge-2.io. Neither resolves publicly today; only cdn.cometchat.io does.
• The mobile UI Kits (React Native, Flutter) ship their sounds inside the app, so they fetch nothing extra.

⚠️ For the Calls team (a product issue, not a docs one): the released JavaScript Calls SDK 5.0.6 hard-codes https://cdn.cometchat-staging.com/calls/v5/… for the background-blur model files. The same paths return 403 on cdn.cometchat.io, so background blur in production depends on a staging CDN. Once those files move to cdn.cometchat.io, the staging row can come off this page.

[ketanyekale]

Re-reviewed after a67a6406. Both blocking issues and all the earlier nits are fixed:

• The Webhooks (inbound) section covers the inbound exception, and the Basic Auth advice matches fundamentals/webhooks.
• The added Dashboard and Widget hosts all resolve in DNS.
• The extensions pattern <extension>-<region>.<family> resolves on all three families for extensions, polls, reactions, stickers, whiteboard and document.
• One correction to my earlier comment: document.cometchat.io doesn't resolve, so document-<region> is the right host.
• Nav, redirects and internal links check out, and the branch is level with main.

One thing left before I approve: the three rows flagged above for a maintainer.

App ID hosts are wildcard DNS records: a made-up App ID resolves on api-us, websocket-us and call-us. So a pattern that doesn't resolve is missing for every app, not only the dev app.

Row	Page says	DNS shows
Moderation (L79)	<appId>.rule-<region> on all three families	Resolves on no family, in any region. rule-<region>.cometchat.io without an App ID resolves on cometchat.io only.
AI Agent Service (L77)	All three families	cometchat.io only
CDN (L109)	cdn.cometchat.io, cdn.cc-cluster-2.io, cdn.cc-edge-2.io	Only cdn.cometchat.io resolves; cdn.cc-edge-2.io fails as well as cdn.cc-cluster-2.io.

All three contradict L70, "Each of these runs on all three runtime families". Suggested fix: move AI Agent Service and CDN to cometchat.io-only, and either confirm with infra which host clients use for Moderation or drop that row.

Nits

• metrics-<region>.cc-cluster-2.io resolves but isn't listed (L113).
• The 443-only Ports row says "Flutter SDKs" without a version. v5 is verified; does v4, still documented under sdk/flutter/v4/, also connect over WSS only?
• The PR description doesn't mention that docs.json drops the duplicated User-Roles and Guides groups.

[raj-dubey1]

@ketanyekale thanks, all items from your 30 Sep review are addressed in d3dc052. Every host was checked against 8.8.8.8, and App ID patterns were tested with a made-up App ID because of the wildcard DNS.

1. AI Agent Service: moved to the cometchat.io-only list. <anyAppId>.ai-agent-service-{us,eu,in}.cometchat.io resolves; the cc-cluster-2.io and cc-edge-2.io variants are NXDOMAIN for every region.
2. CDN: now cdn.cometchat.io only. cdn.cc-cluster-2.io and cdn.cc-edge-2.io are NXDOMAIN.
3. Moderation: <appId>.rule-<region>.<family> is NXDOMAIN everywhere, so that pattern is gone. The real host is rule-<region>.cometchat.io with no App ID prefix: it resolves for us, eu and in, and rule-eu.cometchat.io is a CNAME to ccpro-eu-moderation-service-green-x86.eu-west-1.elasticbeanstalk.com. It's now listed in the cometchat.io-only table. rule-<region> doesn't exist on cc-cluster-2.io or cc-edge-2.io.
4. Metrics: added metrics-<region>.cc-cluster-2.io. It resolves for us, eu and in, with CNAMEs to metrics-*.cometchat.io.
5. Flutter v4 ports: it's not 443-only. cometchat_sdk 4.1.3 has no socket client of its own; it wraps native chat-sdk-android 5.0.1 and iOS CometChatSDK 4.1.3, so it moves to the native row (443, 5222, 7443). Flutter UI Kits v4 and v5 depend on it. Flutter SDK v5 (cometchat_sdk 5.0.8) has its own Dart WSS client defaulting to 443, so it and Flutter UI Kit v6 stay in the 443-only row.
6. PR description: it now says docs.json also removes the duplicated User-Roles and Guides groups. Both pages are still in the nav once.

The other rows still resolve for a made-up App ID on all three families: api, apiclient, call, websocket, apivcb, apimgmt and campaigns.

[raj-dubey1]

Addressed the latest review in 196f008. The new hosts come from the shipped SDKs and a live call, not from guesses.

P1.1: Calling hosts (new "Calling (voice and video)" section, plus the Ports row). I joined a real two-person call with @cometchat/calls-sdk-javascript 5.0.6 on the us dev app and recorded every request, WebSocket and ICE server:

Host	What it is	Evidence
<appId>.xmpp.rtcv5-<region>.cometchat.io	Call signalling (WSS 443)	The only WebSocket the call opened: wss://<appId>.xmpp.rtcv5-us.cometchat.io/xmpp-websocket
turn.rtcv5-<region>.cometchat.io	Media relay, TURN over TLS on TCP 443	iceServers: turns:turn.rtcv5-us.cometchat.io:443?transport=tcp; the call connected through a relay candidate

• Regions: both hosts resolve for us, eu and in. None of them exist on cc-cluster-2.io or cc-edge-2.io.
• Media servers: the SFU is reached by IP address, sent during call setup, so there's no hostname to list. The page now says so, and names TURN on 443 as the fallback that prevents "rings but no audio".
• Where rtcv5 comes from: the app settings returned by /v3.0/me, which carry WEBRTC_HOST: rtcv5-us.cometchat.io.
• rtc.cometchat.io / conference.rtc.cometchat.io from the Calls API reference: the Calls SDK v5 never contacted either, and conference.rtc doesn't resolve. rtc-<region>.cometchat.io is referenced by the iOS SDK binary and resolves, so it's listed.

P1.2: Ports 5222/7443 and the "Legacy WebSockets" host.

• Server settings: the /v3.0/me app settings tell every SDK to connect to CHAT_HOST_APP_SPECIFIC: <appId>.websocket-<region>.cometchat.io on CHAT_WSS_PORT: 443.
• iOS SDK 4.1.10 (latest): its CometChatSocketController reads exactly those keys (CHAT_HOST_APP_SPECIFIC, CHAT_WSS_PORT) and uses a WebSocket library (Starscream).
• Android SDK 5.0.7 (latest): it depends only on OkHttp, with no XMPP library. Its strings are obfuscated, so this one is inferred, not read.
• Port probe (made-up App ID): ws-us has 443/5222/5223/7443 open; websocket-us has 443 only.

So current native SDKs use 443 like everything else. 5222/7443 belong to <appId>.ws-<region>.cometchat.io, used by older native SDK versions. The page now says this in the Runtime table, the native Ports row and the Note, and names the host next to the ports.

⚠️ For the SDK team: please confirm which native SDK versions still use ws-<region> on 5222/7443. That would let the page name a version cut-off instead of "older versions".

P2: page location. Moved to fundamentals/network-allowlist.mdx, updating the nav entry, canonical URL and both inbound links. The page was never live, so no redirect is needed.

Also fixed:

• Wildcard warning: it now covers three-label-deep hosts (<appId>.xmpp.rtcv5-<region>.cometchat.io).
• Build/CI table: adds library.cometchat.io, which Swift Package Manager uses for the iOS SDK's WebSocket library.

The review text I received was cut off after the page-location nit, so if there were more P2 items, please re-post them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgVCxHs3h8m72GXvC8HaV1

[raj-dubey1]

Addressed in 87da80f, and the PR description is rewritten to match the page.

• Cut-off for 5222/7443: it's native iOS/Android SDK v2.x (Android pro-android-chat-sdk 2.4.x and earlier, iOS CometChatPro 2.4.2 and earlier). The SDK history shows it:

  • v2.x used raw XMPP. iOS 2.4.2 embeds XMPPFramework, and Android 2.4.x depends on Smack (smack-tcp).
  • v3.0 onward uses a WebSocket. iOS 3.x and 4.x read CHAT_HOST_APP_SPECIFIC / CHAT_WSS_PORT from the app settings and use Starscream; Android 3.0.0 through 5.0.7 depend only on OkHttp.

  The page names those versions and says how to check an app's SDK version. Flutter SDK v4 wraps native SDKs from v3.0 onward, so it moved to the 443-only row.

• rtc-<region>.cometchat.io: it serves the "CometChat Web" call screen that the Chat SDKs' older built-in calling loads in an iframe (startCall via the WEBRTC_WEB_FRONTEND_HOST setting; the iOS SDK hard-codes rtc-%@.cometchat.io). The page now says that, and that it's needed only by apps still on that calling path.

• Background blur: cdn.cometchat.io is listed for Calls SDK releases after 5.0.6, and cdn.cometchat-staging.com for 5.0.6 and earlier only. Today the blur files still return 403 on cdn.cometchat.io, so the staging row should stay until the fixed release ships.

• Earlier nits:

  • The intro now says CometChat's own hosts are on four domains and points to the third-party hosts.
  • The cc-cluster-2.io and cc-edge-2.io labels now include metrics, Dashboard backends and (for cluster) UI Kit sounds.
  • api-explorer.cometchat.com and mcp.cometchat.com are added as optional tooling hosts. Both resolve.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgVCxHs3h8m72GXvC8HaV1

[raj-dubey1]

Dropped cdn.cometchat-staging.com from the page. Background-blur model files are now listed on cdn.cometchat.io only, since the Calls SDK fix moving them to production ships in the next release. Note: on 5.0.6 they still load from staging until then.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgVCxHs3h8m72GXvC8HaV1

[raj-dubey1]

Fixed: "three hosts" → "two hosts" (L38), and the intro's "a few third-party hosts" → "two third-party hosts" to match. Both are fonts.googleapis.com and fonts.gstatic.com now that the staging CDN is gone.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NgVCxHs3h8m72GXvC8HaV1