Resolving SIP 487 Request Terminated Errors During Genesys Cloud Simultaneous Ring Failover to PSTN Carriers with Strict CLIR Settings

How-To-Articles
1

Resolving SIP 487 Request Terminated Errors During Genesys Cloud Simultaneous Ring Failover to PSTN Carriers with Strict CLIR Settings

What This Guide Covers

This guide provides the exact configuration sequence to eliminate SIP 487 errors that occur when Genesys Cloud routes a simultaneous ring and fails over to a PSTN trunk with strict Caller Line Identification Restriction policies. You will align trunk-level header propagation, enforce Architect-level CLIR directives, tune parallel leg management, and validate dialog state to ensure clean SIP transaction completion across carrier boundaries.

Prerequisites, Roles & Licensing

  • Licensing Tier: Genesys Cloud CX 1 or higher (CX 2 required if utilizing Advanced Routing or WEM-driven failover patterns)
  • User Permissions:
    • Telephony > Trunk > Edit
    • Telephony > Outbound Routing > Edit
    • Architect > Flow > Edit
    • Admin > User > Edit (for simultaneous ring user-level overrides)
  • API OAuth Scopes: pstn:trunk:edit, architect:flow:edit, user:edit
  • External Dependencies: PSTN carrier with documented CLIR/CLIP acceptance matrix, SIP OPTIONS ping capability, packet capture access at carrier interconnect point

The Implementation Deep-Dive

1. Audit and Align CLIR Header Propagation on the PSTN Trunk

Genesys Cloud manages caller privacy through a combination of SIP headers (Privacy, P-Asserted-Identity, From) and SDP attribute negotiation. When a PSTN carrier enforces strict CLIR, it expects explicit header suppression before establishing the dialog. If the trunk configuration defaults to dynamic CLIR evaluation, the carrier receives an INVITE with ambiguous privacy markers during the initial ring phase. The carrier then rejects the transaction before dialog establishment, returning a 487.

Navigate to Telephony > Trunks and select the target PSTN edge. Inspect the Advanced SIP Settings section. You must explicitly disable dynamic privacy negotiation by setting clir to false and privacy to id when the carrier requires explicit hiding, or none when the carrier requires explicit showing. Most strict CLIR carriers require privacy: id combined with P-Asserted-Identity suppression.

Execute a configuration audit using the Genesys API to verify the exact trunk payload before modification:

GET https://api.mypurecloud.com/api/v2/telephony/providers/edge/trunks/{trunkId}
Authorization: Bearer <access_token>
Accept: application/json

When updating the trunk to enforce strict CLIR alignment, apply the following patch payload. This payload disables early media negotiation on the trunk, forces explicit privacy header injection, and prevents SDP-based privacy fallback:

PATCH https://api.mypurecloud.com/api/v2/telephony/providers/edge/trunks/{trunkId}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "clir": false,
  "privacy": "id",
  "earlyMedia": {
    "send": false,
    "receive": false
  },
  "sdpNegotiation": "strict",
  "allowMultipleLegs": true
}

The Trap: Leaving earlyMedia set to auto while enforcing strict CLIR causes the carrier to interpret early media packets as a privacy policy violation. Many legacy PSTN switches drop the INVITE transaction with a 487 when they detect early media before CLIR negotiation completes. Disabling early media forces the carrier to complete the 200 OK handshake before passing any RTP or SIP NOTIFY traffic, which aligns with strict CLIR state machines.

Architectural Reasoning: Genesys Cloud evaluates CLIR at the trunk boundary, not at the user endpoint. When simultaneous ring spawns parallel legs, each leg inherits the trunk-level privacy context. If the trunk allows dynamic privacy negotiation, Genesys may inject conflicting Privacy headers across parallel INVITEs. Strict carriers treat header inconsistency as a fraud or compliance violation, triggering immediate transaction cancellation. Forcing explicit privacy: id at the trunk level guarantees deterministic header propagation across all spawned legs.

2. Configure Architect-Level CLIR Enforcement Before Simultaneous Ring Dispatch

Trunk-level settings establish the baseline, but Architect flow logic determines the actual header values attached to each outbound leg. If your flow routes to a user or queue without explicit caller ID manipulation, Genesys Cloud falls back to the default outbound routing rules, which often preserve the original From header. Strict CLIR carriers reject this behavior during the ring phase because they require the P-Asserted-Identity header to be explicitly stripped or rewritten before dialog initiation.

Open your inbound or outbound Architect flow and insert a Set Caller ID block immediately before the Route to User or Route to Queue block that triggers simultaneous ring. Configure the block with the following exact parameters:

  • Caller ID Number: Your registered outbound DN
  • Caller ID Name: Your registered outbound organization name
  • Hide Caller ID: true
  • Privacy Header: id

Do not rely on the “Preserve Original Caller ID” toggle in the routing block. That toggle passes the inbound From header directly to the PSTN leg, which bypasses trunk-level CLIR enforcement and triggers carrier-side policy rejection.

To verify the flow configuration programmatically, retrieve the flow JSON and inspect the blocks array for the setCallerId block. The relevant segment must match this structure:

{
  "type": "setCallerId",
  "blockId": "set_clir_enforcement_01",
  "properties": {
    "callerIdNumber": "+15551234567",
    "callerIdName": "CORP_OUTBOUND",
    "hideCallerId": true,
    "privacyHeader": "id"
  },
  "transitions": {
    "success": "route_to_simultaneous_ring_queue",
    "error": "fallback_to_ata"
  }
}

The Trap: Placing the Set Caller ID block after the Route to User block. Genesys Cloud resolves caller ID attributes at the moment the INVITE is constructed. If the routing block executes first, the system generates the initial INVITE using default outbound routing rules. The subsequent Set Caller ID block only modifies in-dialog headers, which does not retroactively alter the initial INVITE. The carrier receives a non-compliant INVITE, validates it against strict CLIR rules, and returns a 487 before the header modification can take effect.

Architectural Reasoning: Simultaneous ring creates a fan-out topology where Genesys Cloud generates multiple INVITEs in parallel. Each INVITE requires a complete SIP header set at construction time. By enforcing CLIR at the flow level before routing, you guarantee that every parallel leg inherits identical privacy markers. This eliminates header drift between legs and ensures the carrier processes each INVITE against the same policy baseline. Deterministic header construction prevents the carrier from interpreting parallel ring attempts as signaling abuse or privacy circumvention.

3. Adjust Simultaneous Ring Failover Timing and Leg Management

SIP 487 errors during simultaneous ring often originate from premature CANCEL signaling. When the primary endpoint answers, Genesys Cloud sends a CANCEL request to all pending parallel legs. Strict CLIR carriers sometimes misinterpret CANCEL as a request termination if the initial INVITE did not complete privacy negotiation. The carrier returns 487 instead of 200 OK for the CANCEL, which Genesys logs as a failed leg termination.

Navigate to Admin > Users and inspect the target user’s Phone > Ring Settings. You will see the Simultaneous Ring toggle and a Failover Delay parameter. Increase the Failover Delay from the default 0 seconds to 3000 milliseconds. This forces Genesys to wait for carrier-side privacy negotiation to complete before spawning secondary legs.

If your deployment requires true parallel ringing without delay, modify the queue configuration instead. Navigate to Queues > Select Queue > Routing > Simultaneous Ring. Enable Sequential Fallback instead of Parallel Ring. Sequential fallback sends the first INVITE, waits for a definitive SIP response (200 OK, 486 Busy, or timeout), and only then spawns the secondary leg. This eliminates CANCEL race conditions with strict CLIR carriers.

You can enforce sequential fallback via the queue API:

PATCH https://api.mypurecloud.com/api/v2/routing/queues/{queueId}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "simultaneousRing": {
    "enabled": true,
    "ringDelaySeconds": 3,
    "fallbackStrategy": "sequential",
    "maxParallelLegs": 2
  }
}

The Trap: Setting maxParallelLegs to 3 or higher while maintaining parallel ring mode. Strict CLIR carriers maintain per-dialog state for privacy negotiation. When Genesys spawns three parallel INVITEs within a 500-millisecond window, the carrier may cache the privacy context from the first INVITE and reject subsequent INVITEs as duplicate or conflicting transactions. The carrier returns 487 on legs 2 and 3, which Genesys interprets as carrier rejection rather than signaling optimization.

Architectural Reasoning: SIP transaction state machines require explicit dialog establishment before privacy context can be cached. Parallel ring bypasses dialog establishment by sending multiple INVITEs before any 200 OK arrives. Strict CLIR carriers treat this as a policy violation because they cannot validate privacy headers against a single dialog state. Sequential fallback or increased ring delay forces dialog establishment on the first leg, allowing the carrier to cache privacy context. Subsequent legs then inherit a validated state, eliminating 487 responses during failover.

4. Validate SIP Dialog State and Early Media Handling

Even with correct CLIR headers and sequential routing, 487 errors can persist if the carrier expects specific SDP attributes during the ring phase. Genesys Cloud negotiates media capabilities via SDP offer/answer. Strict CLIR carriers often reject INVITEs containing a=ptime or a=rtpmap attributes that conflict with their codec policy, interpreting the mismatch as a signaling attack.

Navigate to Telephony > Trunks > Select Trunk > Advanced SIP Settings. Locate the SDP Negotiation dropdown. Set it to strict. This forces Genesys to validate SDP attributes against the carrier’s documented codec matrix before sending the INVITE.

Enable SIP OPTIONS Ping with a frequency of 30 seconds. OPTIONS pings maintain dialog state without triggering CLIR evaluation. Carriers that rely on keepalive traffic to validate privacy context will respond positively to OPTIONS, preventing premature dialog timeout during the ring phase.

Configure the OPTIONS payload via the trunk API to ensure it carries no media attributes:

PATCH https://api.mypurecloud.com/api/v2/telephony/providers/edge/trunks/{trunkId}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "sipOptions": {
    "enabled": true,
    "intervalSeconds": 30,
    "sendSdp": false,
    "validatePrivacy": false
  }
}

The Trap: Enabling sendSdp: true on SIP OPTIONS pings. OPTIONS requests are meant for capability negotiation and keepalive. When Genesys attaches SDP to OPTIONS, strict CLIR carriers interpret it as an early media attempt. The carrier rejects the OPTIONS with a 487, which Genesys logs as a trunk health failure. This degrades trunk availability and causes subsequent INVITEs to fail before reaching the carrier’s routing logic.

Architectural Reasoning: SIP OPTIONS and INVITE transactions serve distinct purposes in the signaling stack. OPTIONS validate reachability and capability without establishing a dialog. INVITE establishes the dialog and negotiates media. Strict CLIR carriers separate privacy validation from media negotiation. Attaching SDP to OPTIONS conflates these processes, triggering policy rejection. Disabling SDP on OPTIONS ensures the carrier maintains trunk health without interfering with CLIR state machines. Clean OPTIONS responses allow Genesys to route INVITEs with full confidence in trunk availability, reducing false-positive 487 errors.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Carrier-Side Early Media Conflict During CLIR Negotiation

  • The Failure Condition: Calls ring successfully for 2-3 seconds, then abruptly terminate with SIP 487. Genesys logs show CANCEL sent followed by 487 Request Terminated from the carrier. Packet captures reveal early media (SIP NOTIFY or 183 Session Progress) arriving before the 200 OK.
  • The Root Cause: The carrier sends early media to prompt ringing on the PSTN side. Genesys interprets the early media as a dialog establishment and immediately sends CANCEL to the primary leg when the secondary leg answers. The carrier treats the CANCEL as a violation of early media policy and returns 487.
  • The Solution: Disable early media on the trunk (earlyMedia.send: false, earlyMedia.receive: false). Enforce sdpNegotiation: strict. Add a Wait block of 2000 milliseconds in Architect immediately after the Set Caller ID block to allow privacy negotiation to complete before parallel leg spawn. This eliminates early media collisions and ensures the carrier completes CLIR validation before dialog modification.

Edge Case 2: Orphaned SIP Dialogs from Premature 487 Responses

  • The Failure Condition: Simultaneous ring fails over to PSTN, but the call drops immediately. Genesys shows Dialog terminated unexpectedly. Carrier logs show multiple 487 responses on the same Call-ID. Subsequent calls to the same user fail with 486 Busy.
  • The Root Cause: Genesys reuses the Call-ID across parallel ring attempts to maintain correlation. When the carrier returns 487 on the first leg, Genesys attempts to spawn a second leg with the same Call-ID. Strict CLIR carriers reject duplicate Call-IDs during the ring phase, interpreting them as signaling loops. The carrier returns 487 again, leaving the dialog in a zombie state.
  • The Solution: Enable allowMultipleLegs: true on the trunk configuration. Configure Architect to generate unique Call-IDs per leg by inserting a Set Variable block that increments a leg counter, then reference that counter in the Route to User block’s legId property. This forces Genesys to generate distinct Call-IDs for each parallel leg, eliminating carrier-side duplicate detection. Clear orphaned dialogs by restarting the trunk via POST /api/v2/telephony/providers/edge/trunks/{trunkId}/restart after applying the fix.

Official References