Implementing Custom SIP REFER Handling for External Contact Centers
What This Guide Covers
This guide details how to configure SIP trunks, routing flows, and event synchronization to accept, parse, and route SIP REFER requests from external contact centers. You will have a production-ready architecture that captures REFER headers, routes calls to specific internal queues or skills, processes NOTIFY events for call state updates, and handles protocol errors without dropping sessions or corrupting routing state.
Prerequisites, Roles & Licensing
- Licensing Tier: Genesys Cloud CX 2 or CX 3 (CX 2 required for SIP Trunk configuration and Architect routing; CX 3 recommended for advanced routing analytics and WEM integration)
- Permissions:
Telephony > Trunk > EditRouting > Queue > EditRouting > Architect > EditAdministration > Webhook > Create/EditTelephony > Call Flow > Edit
- OAuth Scopes (API-driven configuration):
telephony:trunk:update,routing:architect:edit,webhooks:manage - External Dependencies:
- External contact center SIP endpoint with RFC 3515 compliant REFER implementation
- Carrier or SIP interconnect supporting DSCP 46/EF prioritization
- Internal middleware or webhook receiver for NOTIFY event processing (if external ticketing/CRM sync is required)
The Implementation Deep-Dive
1. Configuring the SIP Trunk for REFER Acceptance
External contact centers use SIP REFER to signal call transfers, callback requests, or session handoffs. By default, many platform SIP trunks reject REFER or drop the request to prevent unauthorized routing manipulation. You must explicitly enable REFER acceptance and map the incoming request to a routing context that preserves caller ID, external metadata, and session state.
Navigate to Telephony > SIP Trunks and select the trunk connected to the external contact center. Enable the Accept REFER requests toggle. This setting instructs the platform SIP stack to respond with 202 Accepted instead of 403 Forbidden or 405 Method Not Allowed. You must also configure the Refer-To header parsing behavior. Set the Refer-To mapping to Routing Flow and assign the dedicated Architect flow you will build in the next step.
The Trap: Leaving the Refer-To mapping set to Direct Extension or Queue causes the platform to bypass routing logic entirely. When an external partner sends Refer-To: sip:overflow@genesys.example.com, the platform attempts to match a literal destination. If that destination does not exist in the dial plan, the call fails with 404 Not Found. More critically, you lose the ability to apply security filters, skill routing, or compliance recording rules. Always route REFER through an Architect flow that validates the Referred-By header and applies routing policies before destination resolution.
Architectural Reasoning: SIP REFER is a dialog management method, not a media path. The platform must acknowledge the REFER, initiate a new INVITE to the target, and return a 202 Accepted to the originator. The originator then expects a NOTIFY containing the final status. If you skip the routing flow, the platform cannot inject recording policies, compliance checks, or WFM availability rules. Routing through Architect ensures every REFER-triggered session enters the same state machine as inbound calls, guaranteeing consistent telemetry and compliance enforcement.
2. Architecting the REFER Routing Logic
The routing flow must parse SIP headers, validate the external partner, apply security controls, and route to the correct destination. Begin by creating a new Architect flow named External_REFER_Handler. Set the Entry Point to SIP Trunk REFER. This entry point automatically populates System.SIP.ReferTo, System.SIP.ReferredBy, and System.SIP.CallID.
Add a Set Variable block to extract and normalize the Refer-To URI. Use the following expression:
regex_replace(System.SIP.ReferTo, "sip:(.*)@.*", "$1")
This strips the domain and isolates the target identifier. External partners often send fully qualified URIs that do not match internal routing keys. Normalization prevents routing mismatches.
Next, add a Decision block to validate the Referred-By header against an allowlist. Store approved partner SIP URIs in a Data Source or External API response. If the header does not match, route to a Play Prompt block with a 403 Forbidden simulation, then terminate the flow with a 403 SIP response. This prevents spoofed REFER requests from injecting traffic into your queues.
After validation, route to a Route to Queue or Route to Skill block based on the normalized target. If the external partner uses dynamic routing keys, map them to internal skills using a Data Lookup block. Configure the Wrap-up Code to REFER_TRANSFER for downstream analytics.
The Trap: Using System.SIP.ReferTo directly in a Route to Queue block without normalization or validation causes silent routing failures. The platform attempts to match the raw URI against queue names or skill groups. If the URI contains parameters like ?transport=UDP or ;user=phone, the match fails. The call drops with no error logged in the standard call detail record. Always normalize the URI and log the raw header to a custom field before routing.
Architectural Reasoning: REFER routing must be idempotent and stateless at the entry point. The platform does not maintain REFER dialog state across flow executions. Each REFER request is treated as a new routing event. By normalizing headers and validating against an allowlist, you create a deterministic routing path. This design also enables you to apply WFM availability rules, IVR overflow logic, and compliance recording without modifying the external partner’s SIP stack. If you need to correlate REFER events with WFM scheduling, reference the Workforce Management Integration Patterns guide for skill-level availability mapping.
3. Processing NOTIFY Events and State Synchronization
After the platform responds with 202 Accepted, the external contact center sends a NOTIFY request containing the final status of the REFER operation. The NOTIFY body typically contains a Message/Reference-Info payload or a custom XML/JSON block. You must configure a webhook or internal API endpoint to capture and process these events.
Create a Webhook under Administration > Webhooks with the following configuration:
- Name:
External_REFER_NOTIFY_Handler - Endpoint URL:
https://your-middleware.example.com/api/v1/genesys/refer-notify - HTTP Method:
POST - Authentication:
OAuth 2.0 Client Credentials - Scopes:
event:webhook:subscribe,telephony:call:view - Event Filters:
SIP NOTIFY,Call Status Change
The platform will POST a JSON payload to your endpoint. Your middleware must parse the Subscription-State and Reference-Info headers. A successful transfer returns Subscription-State: active;expires=3600 with a 200 OK in the NOTIFY body. A failed transfer returns Subscription-State: terminated;reason=no-target with a 481 Call/Transaction Does Not Exist or 404 Not Found.
Configure your webhook receiver to acknowledge with 200 OK within 3 seconds. Failure to respond within the timeout window causes the platform to retry the webhook up to three times, creating duplicate state updates in your CRM or ticketing system.
The Trap: Returning a 202 Accepted or 204 No Content from your webhook receiver causes the platform to treat the event as unprocessed and retry indefinitely. The platform expects a 200 OK for synchronous webhook delivery. Additionally, ignoring the Subscription-State header leads to phantom session tracking. If the external partner terminates the REFER dialog, you must update your internal state to CLOSED or TRANSFERRED. Failing to do so leaves orphaned sessions in your analytics, skewing abandonment rates and WFM forecasting.
Architectural Reasoning: NOTIFY processing is a fire-and-forget pattern from the SIP stack perspective. The platform does not block call processing while waiting for your webhook response. Your middleware must be designed for async event consumption with idempotency keys. Use the System.SIP.CallID and System.SIP.From fields as composite keys to prevent duplicate processing. This architecture aligns with event-driven design principles and ensures your CRM, ticketing, and speech analytics systems receive consistent state updates. If you integrate with speech analytics, ensure the NOTIFY handler tags the session with the correct RecordingPolicy ID to prevent media ingestion failures.
4. Error Handling and Failover Pathways
SIP REFER operations fail frequently due to network partitions, carrier timeouts, or misconfigured external endpoints. You must design explicit failover pathways for 481, 403, 404, and 503 responses. The platform does not automatically retry REFER requests. You must handle retries at the routing flow level or in your middleware.
Add a Catch Exception block in your Architect flow to capture SIP routing failures. Route 481 Call/Transaction Does Not Exist to a Play Prompt block with a fallback IVR menu. This typically indicates the external partner terminated the dialog before the platform could initiate the new INVITE. Route 403 Forbidden to a Log Event block and terminate the session. This indicates a security policy violation or invalid Referred-By header. Route 404 Not Found to a Set Variable block that updates the target to a default overflow queue, then re-route. Route 503 Service Unavailable to a Wait block with exponential backoff, then retry the routing decision up to two times.
Configure your middleware to log all NOTIFY events with a failed or terminated state to a dead-letter queue. Implement a reconciliation job that compares platform call detail records against middleware session logs. Discrepancies indicate missed NOTIFY events or webhook delivery failures.
The Trap: Implementing synchronous retries in the Architect flow without exponential backoff causes thundering herd conditions during carrier outages. The platform attempts to re-route the same REFER request immediately, exhausting trunk capacity and triggering carrier rate limiting. Always use a Wait block with randomized jitter (e.g., random(2000, 5000) milliseconds) before retrying. Additionally, failing to log 481 responses causes silent call drops that appear as normal terminations in reports. Explicitly map SIP error codes to custom wrap-up codes for accurate failure analysis.
Architectural Reasoning: REFER error handling must be deterministic and observable. The SIP protocol does not guarantee delivery of NOTIFY events. Network partitions, NAT timeouts, and carrier load balancing can drop dialog state. By implementing explicit error routing and middleware reconciliation, you create an audit trail for every REFER operation. This design also enables you to apply circuit breaker patterns in your middleware. If the external partner returns 503 repeatedly, your middleware can temporarily disable the webhook subscription and fall back to standard inbound routing. This prevents cascading failures during partner outages.
Validation, Edge Cases & Troubleshooting
Edge Case 1: REFER Dialog Mismatch During High Concurrency
The failure condition: External contact centers send multiple REFER requests in rapid succession. The platform responds with 202 Accepted but fails to match the subsequent NOTIFY to the correct session. Calls drop with 481 Call/Transaction Does Not Exist.
The root cause: The platform uses Call-ID and From-Tag to correlate REFER dialogs. Under high concurrency, carrier load balancers or SIP proxies may modify the From-Tag or strip dialog parameters. The platform cannot match the NOTIFY to the original REFER, treating it as an orphaned event.
The solution: Configure your SIP trunk to preserve From-Tag and Call-ID by disabling SIP Header Normalization. Add a Set Variable block in the Architect flow to capture the raw Call-ID and From-Tag before routing. Pass these values to your webhook receiver as custom headers. Implement dialog correlation in your middleware using the exact SIP transaction identifiers. If your carrier modifies headers, deploy a SIP proxy or B2BUA that preserves dialog state. Reference the SIP Interconnect Security and Header Preservation guide for proxy configuration patterns.
Edge Case 2: NOTIFY Payload Schema Drift from External Partners
The failure condition: External contact center vendors update their SIP stack or middleware. The NOTIFY payload changes from Message/Reference-Info to custom JSON. Your webhook receiver fails to parse the event, leaving sessions in a pending state.
The root cause: External partners treat NOTIFY bodies as flexible payloads. The RFC 3515 specification allows custom media types. Your webhook receiver expects a fixed schema and throws a parsing exception on drift.
The solution: Implement schema-agnostic parsing in your webhook receiver. Use a content-type switch to handle application/json, message/sipfrag, and application/xml. Log the raw NOTIFY body to a message queue for offline analysis. Implement a fallback parser that extracts status codes from SIP headers when the body is unparseable. Configure your webhook receiver to return 200 OK for all successfully received events, regardless of parsing success. Flag unparseable events for manual review. This approach ensures you never block SIP dialog state while maintaining audit compliance.