Configure Retell SIP REFER controls

Use REFER controls when a Retell transfer function must pass a destination or small piece of call metadata to the receiving SBC. This feature applies to a Cold Transfer that Retell sends as an in-dialog SIP REFER. It does not change warm transfers or ordinary INVITE requests.

The controls are opt in. Existing Retell transfer headers continue to work as before, and the edge removes the private control headers before forwarding a valid REFER.

Configure the number

1. Open Numbers, select the number, and open its Retell transfer header editor.
2. Select one or more transfer functions.
3. In REFER controls, add an embed row for each URI header you want to append, such as X-Customer-ID with the value {{customer_id}}.
4. Optionally add a complete sip: or sips: URI in Refer-To override.
5. Review the preview and apply the change.

The editor writes these friendly fields to the generated wire names X-RE-X-<suffix> and X-RE-Refer-To. You do not need to add those private names yourself. The same controls are available from both number assignment entry points.

Use the tenant API

The tenant-token API exposes the same workflow:

curl --fail-with-body \
  "https://api.sipsandwich.ai/api/v1/phone-numbers/$PHONE_NUMBER_ID/retell-transfer-headers" \
  -H "Authorization: Bearer $SIPSANDWICH_API_TOKEN"

Apply an override and one dynamic URI header to selected transfer functions:

curl --fail-with-body -X PATCH \
  "https://api.sipsandwich.ai/api/v1/phone-numbers/$PHONE_NUMBER_ID/retell-transfer-headers" \
  -H "Authorization: Bearer $SIPSANDWICH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "functionIds": ["transfer-function-id"],
    "referControls": {
      "override": "sip:200@sbc.example.com;transport=tcp",
      "embedHeaders": [
        { "name": "X-Customer-ID", "value": "{{customer_id}}" }
      ]
    }
  }'

functionIds limits the update to the selected transfer functions. The headers field is optional: when omitted, the API supplies its legacy X-Original_Caller_ID: {{original_caller_id}} default and merges it with each selected function's existing ordinary mappings. Supplied ordinary headers are also merged; use removeHeaderNames to remove existing rows by name. REFER controls are merged through the same selected-function update.

The optional retellWorkspaceId query parameter selects a tenant-owned additional Retell workspace. The API requires a tenant API token; reads use the tenant read permission and updates use the tenant admin permission. Phone numbers and workspace assignments are checked against the token's tenant.

What reaches the SBC

For this incoming REFER:

Refer-To: <sip:100@original.example?existing=yes>
X-RE-Refer-To: sip:200@sbc.example.com;transport=tcp?override=yes
X-RE-X-Customer-ID: customer 42&west

The SIP edge applies the override first, then appends the embed header with percent encoding while preserving existing URI parameters, display names, and query headers. The resulting header is equivalent to:

Refer-To: <sip:200@sbc.example.com;transport=tcp?override=yes&X-Customer-ID=customer%2042%26west>

The private X-RE-* headers are stripped before the REFER leaves the edge. Only a Retell-originated, authenticated in-dialog REFER can use the controls. Provider-originated REFERs remain signaling requests but their control headers are ignored and stripped. Controls on other methods are stripped and never become ordinary SIP headers.

Validation and limits

• Add up to eight embed rows and one override.
• Embed names are X-* names up to 80 characters; values are 1–512 characters.
• The override is a SIP/SIPS URI up to 1,024 characters, or one complete dynamic template such as {{transfer_uri}}.
• Values containing CR/LF, encoded control characters, malformed templates, reserved routing names, or duplicate names are rejected.
• Existing URI query names are compared case-insensitively after decoding the name. A conflicting name is rejected before the request is forwarded.
• The edge preserves signaling only. It does not anchor media or change RTP.

Legacy or unknown X-RE-* rows appear as a value-free warning in the preview. Select the REFER section to remove or replace them. Saving an ordinary header section without changing REFER controls preserves existing metadata.

Retell must send the resulting function as a Cold Transfer using SIP REFER. The setting does not make a warm transfer or an INVITE carry these controls.