Skip to main content

Advanced SIP topology hiding

Topology hiding lets sipsandwich present its public signaling identity in carrier-facing SIP headers while retaining the routing state needed to deliver responses and in-dialog requests to the original endpoint. It is an advanced, opt-in connection setting. Availability depends on the deployment readiness reported by the API.

When to use it​

Use this option when a carrier validates the IP addresses in SIP Via or Contact headers and those headers would otherwise expose a private address. The carrier must authorize the sipsandwich service signaling IP 51.81.131.209 for the connection.

The connection must use IP authentication or SIP digest authentication. SIP registration is not supported for topology hiding because registered Contacts and send sockets are tied to a specific edge. Keep registration connections on the normal routing path.

Both signaling directions must use the sipsandwich service identity: calls from the carrier toward Retell and calls from Retell toward the carrier. A direct Retell-to-carrier route bypasses sipsandwich and cannot be changed by this setting. Configure the carrier's accepted source IPs or CIDRs before enabling the option; an empty provider source allowlist is not eligible.

What changes in a call​

  • Carrier-facing signaling uses the authorized sipsandwich service identity.
  • Call-ID stays unchanged, so tracing and call correlation continue to work.
  • SIP dialog routing state is retained for replies, ACK, CANCEL, BYE, and re-INVITE requests.
  • SDP and RTP are unchanged. This feature handles SIP signaling and does not anchor, transcode, record, or otherwise alter media.

Enable or disable it​

The connection property is topologyHidingEnabled. It defaults to false, so existing connections remain on ordinary SIP routing until you opt in.

Before enabling it, check the connection response's topologyHidingAvailability object. The deployment gate must report that the feature is ready and provide the service identity. A ready deployment does not make an ineligible registration connection or an unauthorized carrier eligible.

When creating or updating a connection:

  • Send topologyHidingEnabled: true to opt in after the eligibility checks pass.
  • Send topologyHidingEnabled: false to turn it off for new calls.
  • Omit the property when updating an existing connection to preserve its current value.

In the portal, open SIP Providers, edit the connection, select Enable advanced SIP topology hiding, and choose Save. The portal applies the same eligibility and deployment-readiness checks as the API.

If readiness or a connection prerequisite is blocked, the API returns 409 instead of enabling the setting. Resolve the reported prerequisite, then retry the update.

Turning the option off does not invalidate an established hidden dialog; it controls new calls. Keep the carrier authorization in place while existing hidden calls finish.

Before you enable a connection​

  1. Confirm that the connection uses IP or digest authentication and has a non-empty provider source IP/CIDR allowlist.
  2. Have the carrier authorize 51.81.131.209 for sipsandwich signaling in both directions, with the required transport and port.
  3. Confirm that the API reports deployment availability for topology hiding.
  4. Enable the option in the portal or send topologyHidingEnabled: true in the API update.
  5. Place an authorized canary call in each direction and verify setup, answer, hangup, and any required in-dialog requests.

The feature does not change the carrier's authentication credentials, caller ID policy, or media path. If the carrier requires media to originate from the signaling IP, that is a separate carrier requirement.