Skip to main content

Forward

Forwards an unanswered incoming call to another number. Unlike <Transfer>, once your call is forwarded, your application will not have any control over either leg of the call. When either leg hangs up, a Disconnect event will be sent to your Call status webhook URL.

Text Content

There is no text content available to be set for the <Forward> verb.

Attributes

AttributeDescription
toNumber to forward the call to. Must be an E.164 formatted number (e.g. +15555551212) or a SIP URI (e.g. sip:user@server.com)
from(optional) Number to use for caller ID on the outgoing leg. Must be in E.164 format (e.g. +15555555555) even if privacy is set to true. If omitted, assumes the "to" number of the original leg.
privacy(optional) Hide the calling number. The callerDisplayName field can be used to customize the displayed name.
callerDisplayName(optional) The caller display name to use when the call is created. May not exceed 256 characters nor contain control characters such as new lines. If privacy is true, only the following values are valid: Restricted, Anonymous, Private, or Unavailable.
callTimeout(optional) The timeout (in seconds) for the callee to answer the call after it starts ringing. If the call does not start ringing within 30s, the call will be cancelled regardless of this value. Range: decimal values between 1 - 300. Default: 30
diversionTreatment(optional) Can be any of the following:
none: No diversion headers are sent on the outbound leg of the transferred call.
propagate: Copy the Diversion header from the inbound leg to the outbound leg. Ignored if there is no Diversion header present on the inbound leg.
stack: After propagating any Diversion header from the inbound leg to the outbound leg, stack on top another Diversion header based on the Request-URI of the inbound call.

Defaults to none. If diversionTreatment is not specified, no diversion header will be included for the transfer even if one came with the inbound call.
diversionReason(optional) Can be any of the following values:
unknown
user-busy
no-answer
unavailable
unconditional
time-of-day
do-not-disturb
deflection
follow-me
out-of-service
away

This parameter is considered only when diversionTreatment is set to stack. Defaults to unknown.
uui(optional) The value of the User-To-User header to send within the outbound INVITE when forwarding to a SIP URI. Must include the encoding parameter as specified in RFC 7433. Only base64 and jwt encoding are currently allowed. This value, including the encoding specifier, may not exceed 256 characters.

Webhooks Received

There are no webhooks received after the <Forward> verb is executed.

Examples

Forward a Call

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Forward from="+15554567890" to="+15557654321"/>
</Response>