Table Of Contents

SIP Pass Through APIs

addHeader

addHeaderValueParameter

addHeaderUriParameter

addRequestUriParameter

addContentBody

SIP Pass Through APIs

---

Cisco Unified CM is a Business to Business User Application (B2BUA) with respect to SIP call processing. The pass through object provides a set of APIs that allows information to be passed from one call leg to the other.

The following SIP Pass Through APIs are availabe:

•addHeader

•addHeaderValueParameter

•addHeaderUriParameter

•addRequestUriParameter

•addContentBody

addHeader

addHeader(header-name, header-value)

Given the string name of a header and value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

Example

Without transparency, Cisco Unified CM ignores the inbound x-nt-corr-id header since it is unknown to it. Effectively, it is stripped off of the inbound INVITE and not included in the outbound INVITE.

To enable pass through of this header, it must be included in the allowHeaders table at the beginning of the script. Then it must be explicitly added to the pass through object during message handling.

Script

M = {}

M.allowHeaders = {"x-nt-corr-id"}

function M.inbound_INVITE(msg)

    local ntcorrid = msg:getHeader("x-nt-corr-id")

    if ntcorrid

    then

        pt = msg:getPassThrough()

        pt:addHeader("x-nt-corr-id", ntcorrid)

    end

end

return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0

.

x-nt-corr-id: 000002bf0f15140a0a@000075447daf-a561119

.

Outbound Message

INVITE sip:1234@10.10.10.2 SIP/2.0

.

x-nt-corr-id: 000002bf0f15140a0a@000075447daf-a561119

.

addHeaderValueParameter

addHeaderValueParameter(header-name, parameter-name [,parameter-value])

Given the name of a header , a parameter name, and a parameter value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The header name and parameter name are required arguments. The parameter-value is optional.

---

Note By default, Contact header value parameters, are passed through independent of any script logic, except the following, which are considered call-leg specific, and are Cisco Unified CM generated as appropriate:
                   - audio
                   - video

---

Example

Without transparency, Cisco Unified CM ignorea the inbound x-tag in the From header since it is unknown to it. Effectively, it is stripped off of the inbound INVITE and not included in the outbound INVITE.

To enable pass through of this header parameter, it must be explicitly added to the pass through object during message handling.

Script

M = {}

function M.inbound_INVITE(msg)

    local xtag = msg:getHeaderValueParameter("From", "x-tag")

    if xtag

    then

        pt = msg:getPassThrough()

        pt:addHeaderValueParameter("From", "x-tag", xtag)

    end

end

return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0

. 

From: <sip:1000@10.10.10.58>;tag=0988bf47-df77-4cb4;x-tag=42

.

Outbound Message

INVITE sip:1234@10.10.10.2 SIP/2.0

.

From: <sip:1000@10.10.10.1>;tag=abcd;x-tag=42

.

addHeaderUriParameter

addHeaderUriParameter(header-name, parameter-name [,parameter-value])

Given the name of a header, a URI parameter name, and a parameter value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The header name and parameter name are required arguments. The parameter value is optional.

Example:

Without transparency, Cisco Unified CM ignores the inbound cca-id parameter in the Contact header URI since it is unknown to it. Effectively, it is stripped off of the inbound INVITE and not included in the outbound INVITE.

To enable pass through of this header URI parameter, it is explicitly added to the pass through object during message handling.

---

Note The parameter, in this example, takes on a different name in the outbound message (i.e. originating cca-id in the outbound message versus cca-id in the inbound message).

---

Script

M = {}

function M.inbound_INVITE(msg)

    local occaid = msg:getHeaderUriParameter("Contact", "cca-id")

    if occaid

    then

        pt = msg:getPassThrough()

        pt:addHeaderUriParameter("Contact", "originating-cca-id", occaid)

    end

end

return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0

. 

Contact: <sip:1000@10.10.10.58;cca-id=LSC.dsn.mil>

.

Outbound Message

INVITE sip:1234@10.10.10.2 SIP/2.0

.

Contact: <sip:1000@10.10.10.1;originating-cca-id=LSC.dsn.mil>

.

addRequestUriParameter

addRequestUriParameter(parameter-name [,parameter-value])

Given a URI parameter name and a parameter value, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The parameter name is a required argument. The parameter value is optional.

---

Note By default, Request-Uri parameters in an initial INVITE, are passed through independent of any script logic, except the following, which are considered call-leg specific, and are CUCM generated as appropriate:
                 - phone-context
                 - trunk-context
                 - tgrp
                 - user

---

Example: The inbound leg creates and passes through a parameter to be placed into the outbound Request URI.

Script

M = {}

function M.inbound_INVITE(msg)

    pt = msg:getPassThrough()

    pt:addRequestUriParameter("from-network", "service-provider")

end

return M

Inbound Message

INVITE sip:1234@10.10.10.1 SIP/2.0

Outbound Message

INVITE sip:1234@10.10.10.2;from-network=service-provider SIP/2.0

addContentBody

addContentBody(content-type, content-body [,content-disposition [,content-encoding 
,[content-language]]])

Given a content-type, content-body, content-disposition, content-encoding, and content-language, this method adds the information to the pass through object for inclusion in the triggered outbound message.

The content-type and content-body are required arguments. The content-disposition, content-encoding, and content-language are optional parameters. If blank or nil is specified for any of these values, the header will not be included as part of the content.

Example:

Without transparency, Cisco Unified CM ignores the inbound INFO message and content body. Using transparency, Cisco Unified CM extracts the proprietary content body sent by a Nortel PBX, extract the DTMF digits from that content body, create a new dtmf-relay content body and pass that through.

Script

M = {}

function M.inbound_INFO(msg)

    local body = msg:getContentBody("application/vnd.nortelnetworks.digits")

    if body

    then

        local digits = string.match(body, "d=(%d+)")

        if digits

        then

            pt = msg:getPassThrough()

            body = string.format("Signal=%d\r\nDuration=100\r\n", digits)

            pt:addContentBody("application/dtmf-relay", body)

        end

    end

end

return M

Inbound Message

INFO sip: 1000@10.10.10.1 SIP/2.0

Via: SIP/2.0/UDP 10.10.10.57:5060

From: <sip:1234@10.10.10.57>;tag=d3f423d 

To: <sip:1000@10.10.10.1>;tag=8942 

Call-ID: 312352@10.10.10.57 

CSeq: 5 INFO 

Content-Type: application/vnd.nortelnetworks.digits

Content-Length: 72

p=Digit-Collection

y=Digits

s=success

u=12345678

i=87654321

d=4

Outbound Message

INFO sip: 1000@10.10.10.58 SIP/2.0 

Via: SIP/2.0/UDP 10.10.10.1:5060 

From: <sip:1234@10.10.10.1>;tag=ef45ad 

To: <sip:1000@10.10.10.58>;tag=1234567

Call-ID: 475623@10.10.10.1 

CSeq: 5 INFO 

Content-Type: application/dtmf-relay

Content-Length: 26

Signal=4

Duration=100