# &adminguide;

## Overview

The module implements the Diversion extensions as per draft-levy-sip-diversion-08. The diversion extensions are useful in various scenarios involving call forwarding. Typically one needs to communicate the original recipient of the call to the PSTN gateway and this is what the diversion extensions can be used for.

The draft-levy-sip-diversion-08 is expired!! See IETF I-D tracker.

## Dependencies

### &osips; Modules

None.

### External Libraries or Applications

The following libraries or applications must be installed before running &osips; with this module loaded:

- None.

## Exported Parameters

### `suffix` (string)

The suffix to be appended to the end of the header field. You can use the parameter to specify additional parameters to be added to the header field, see the example.

Default value is (empty string).

#### `suffix` usage

    modparam("diversion", "suffix", ";privacy=full")

## Exported Functions

### `add_diversion(reason [[,uri], counter])`

The function adds a new diversion header field before any other existing Diversion header field in the message (the newly added Diversion header field will become the topmost Diversion header field). The inbound (without any modifications done by the proxy server) Request-URI will be used as the Diversion URI.

Meaning of the parameters is as follows:

- reason - The reason string to be added as the reason parameter

- uri - The URI to be added in the header. If missing the unchanged RURI from the original message will be used.

- counter - Diversion counter to be added to the header, as defined by the standard.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `add_diversion` usage

    ...
    add_diversion("user-busy");
    ...

## Diversion Example

The following example shows a Diversion header field added to INVITE message. The original INVITE received by the user agent of sip:bob@sip.org is:

    INVITE sip:bob@sip.org SIP/2.0
    Via: SIP/2.0/UDP 1.2.3.4:5060
    From: "mark" <sip:mark@sip.org>;tag=ldgheoihege
    To: "Bob" <sip:bob@sip.org>
    Call-ID: adgasdkgjhkjha@1.2.3.4
    CSeq: 3 INVITE
    Contact: <sip:mark@1.2.3.4>
    Content-Length: 0

The INVITE message is diverted by the user agent of sip:bob@sip.org because the user was talking to someone else and the new destination is sip:alice@sip.org :

    INVITE sip:alice@sip.org SIP/2.0
    Via: SIP/2.0/UDP 5.6.7.8:5060
    Via: SIP/2.0/UDP 1.2.3.4:5060
    From: "mark" <sip:mark@sip.org>;tag=ldgheoihege
    To: "Bob" <sip:bob@sip.org>
    Call-ID: adgasdkgjhkjha@1.2.3.4
    CSeq: 3 INVITE
    Diversion: <sip:bob@sip.org>;reason=user-busy
    Contact: <sip:mark@1.2.3.4>
    Content-Length: 0