PJSIP_INHERITABLE_HEADER()

Since 20.19.0, 22.9.0, 23.3.0 Functions

Adds, updates or removes the specified [[term:sip]] header from a [[term:pjsip]] or non-PJSIP [[term:channel|channel]] to be inherited to an outbound PJSIP channel.

Last reviewed 2026-08-22

PJSIP_INHERITABLE_HEADER(action,name[,number])

Description

PJSIP_INHERITABLE_HEADER allows you to write specific SIP headers on a calling channel to be inherited by an outbound PJSIP channel.

Examples:

Add an inheritable X-Myheader header with the value of myvalue

exten => 1,1,Set(PJSIP_INHERITABLE_HEADER(add,X-MyHeader)=myvalue)

Add an inheritable X-Myheader header with an empty value

exten => 1,1,Set(PJSIP_INHERITABLE_HEADER(add,X-MyHeader)=)

Add an inheritable X-MyHeader that will be inherited by child channel

exten => 1,1,Set(PJSIP_INHERITABLE_HEADER(add,X-MyHeader)=myvalue)

Update the value of the inheritable header named X-Myheader to newvalue

; 'X-Myheader' must already exist or the call will fail.
exten => 1,1,Set(PJSIP_INHERITABLE_HEADER(update,X-MyHeader)=newvalue)

Remove all inheritable headers whose names exactly match X-MyHeader

exten => 1,1,Set(PJSIP_INHERITABLE_HEADER(remove,X-MyHeader)=)

Remove all inheritable headers that begin with X-My

exten => 1,1,Set(PJSIP_INHERITABLE_HEADER(remove,X-My*)=)

Note

If you call PJSIP_INHERITABLE_HEADER in a normal dialplanThe core call-routing configuration of Asterisk, written mostly in extensions.conf as contexts, extensions, and priorities that decide how every call is handled. Full definition → contextA named section of the dialplan that groups extensions. Calls enter a specific context and can only reach extensions visible from it, making contexts the basic unit of call routing and security. you'll be operating on the caller's channel which will then be inherited to the callee's (outgoing) channel. Inherited headers can be updated or removed via PJSIP_INHERITABLE_HEADER in a pre-dial handler. Headers added via PJSIP_INHERITABLE_HEADER are separate from headers added via PJSIP_HEADER. A header added via PJSIP_INHERITABLE_HEADER can only be or removed modified by PJSIP_INHERITABLE_HEADER. A header added via PJSIP_HEADER can only be modified or removed by PJSIP_HEADER.

Set and modify headers on callee channel

[handler]
exten => modheader,1,Set(PJSIP_INHERITABLE_HEADER(update,X-MyHeader)=myvalue)
    same => n,Set(PJSIP_INHERITABLE_HEADER(update,X-MyHeader2)=myvalueX)
    same => n,Set(PJSIP_INHERITABLE_HEADER(remove,X-MyHeader2)=)

[somecontext]
exten => 1,1,Set(PJSIP_INHERITABLE_HEADER(add,X-MyHeader1)=myvalue1)
    same => n,Set(PJSIP_INHERITABLE_HEADER(add,X-MyHeader2)=myvalue2)
    same => n,Set(PJSIP_INHERITABLE_HEADER(add,X-MyHeader3)=myvalue3)
    same => n,Dial(PJSIP/${EXTEN},,b(handler^modheader^1))

Arguments

action required
- add - Adds a new header name to this channel.
- update - Updates instance number of header name to a new value. The header must already exist.
- remove - Removes all instances of previously added headers whose names match name. A * may be appended to name to remove all headers beginning with name. name may be set to a single * to clear all previously added headers. In all cases, the number of headers actually removed is returned.
name required - The name of the header.
number - If there's more than 1 header with the same name, this specifies which header to read or update. If not specified, defaults to 1 meaning the first matching header. Not valid for add or remove.

User Notes

Know a tip or gotcha for this topic? Share it below and help others.

Contribute a note

Share a tip, gotcha, or practical example. Keep it under 2000 characters. No questions (use the Asterisk community forums for support). Wrap code in backticks.