Skip to main content
The sip:refer verb transfers a call and disconnects it from the Voice Gateway. This verb sends a REFER message to the carrier (SIP trunk) or SIP phone. The carrier or SIP phone must support REFER for the transfer to succeed. 
{
  "verb": "sip:refer",
  "referTo": "+49XXXXXXXXXXX",
  "id": "unique-id-123",
  "referredBy": "sip:caller@example.com",
  "actionHook": {
    "url": "/action",
    "referStatus": "202",
    "final_referred_call_status": "200",
    "eventHook": {
      "event": "transfer-status",
      "call_status": "180"
    }
  },
  "eventHook": "/event",
  "headers": {
    "X-Custom-Header": "Value"
  }
}

​
Configuration

The following table lists the available parameters:
ParameterTypeDescriptionRequired
referTostringThe target of the call transfer. A SIP URI, phone number, or user identifier specifying who should receive the call.Yes
idstringA unique identifier for this verb instance. Used for event notifications when notifyEvents is enabled.No
referredBystringThe source or initiator of the call transfer. A SIP URI, phone number, or user identifier specifying who is transferring the call. If the value isn’t provided, it defaults to the identity of the party being transferred.No
actionHookstring | objectA webhook to receive an HTTP POST when the call is completed. The default value is refer.No
actionHook.referStatusstringThe SIP status response to the REFER request.No
actionHook.final_referred_call_statusstringThe final SIP status of the subsequent call to the transferee. Provided only when the REFER is accepted and NOTIFY messages are received from the remote party.No
actionHook.eventHook.eventstringThe transfer event status. Indicates the state of the follow-on call.No
actionHook.eventHook.call_statusstringThe SIP status received in a NOTIFY after a successful REFER, for example, 180 Ringing or 200 OK.No
eventHookstring | objectA webhook that receives an HTTP POST when NOTIFY messages about the follow-on call status are received.No
headersobjectAn object containing additional SIP headers to include in the response.No

​
Completion

The verb completes when one of the following occurs:
  • A failure response is received for the REFER request.
  • A 202 Accepted response is received, followed by NOTIFY indicating the final status of the follow-on call.
  • actionHook returns the final result details. Optionally, eventHook receives each NOTIFY after a successful REFER request.

​
Events

After the verb completes, one of the following events occurs:
  • TRANSFER_REFER_SUCCESS — when refer_status is 202 Accepted and final_referred_call_status is 200 OK.
  • TRANSFER_REFER_ERROR — when refer_status is 202 Accepted and final_referred_call_status is any other value, for example, 410 Gone, 408 Request Timeout, or 5xx. Any configured failover or error hook runs when this event fires.
Last modified on June 10, 2026