Define the message and channel before listing names
Asterisk documents PJSIP_HEADERS() as returning header names from an INVITE message. In a normal inbound PJSIP dialplan, bind the result to the current incoming channel and preserve the request method, timestamp, Call-ID, CSeq, endpoint and channel identifiers. Do not generalize that list to REGISTER, OPTIONS, a response, an outbound callee request or a later in-dialog request.
A list observed on one channel is evidence about the INVITE available to that channel at that dialplan point. It is not a transaction history and does not establish what an upstream sender originally emitted before proxies or Asterisk processing.
Check release and module availability
PJSIP_HEADERS() is documented from Asterisk 16.20.0 and 18.6.0 and is provided by res_pjsip_header_funcs. Confirm the installed branch, maintenance release and loaded module instead of inferring support from current online documentation or a different node in a cluster.
An unknown function is a version or module boundary. An empty result on a supported system is a different symptom and should stay attached to the exact channel, request and prefix used.
Use the prefix as a discovery filter
The optional argument limits output to names matching the supplied prefix. Asterisk documents ${PJSIP_HEADERS(Co)} as an example that can return Contact,Content-Length,Content-Type, and ${PJSIP_HEADERS(X-)} as a way to enumerate extended names. An omitted prefix requests the complete name list exposed by the function.
Treat the result as comma-separated names. Preserve the literal prefix used and compare a restricted query with the unfiltered list before concluding that a header family is absent.
Separate unique names from values and repetitions
PJSIP_HEADERS() omits values and includes a repeated name only once. It therefore cannot establish a header value, the number of occurrences or the wire order of repeated rows. After identifying an intended name, use PJSIP_HEADER(read,name,number) to read the selected inbound instance; the number defaults to the first.
RFC 3261 makes the relative order of repeated rows significant and permits multiple rows only under defined rules, with authentication-field exceptions. Preserve the selected instance and the bounded SIP message when repeated values matter.
Respect SIP name and compact-form semantics
RFC 3261 defines header-field names as case-insensitive and permits compact names for several common fields without changing message semantics. Keep the literal output for audit, but normalize only according to the protocol and the consumer contract. Do not assume a custom string comparison, database key or allow-list applies SIP comparison rules automatically.
A name present in the inventory does not validate its value, authorize the sender or prove the field is meaningful for that request. Apply a narrow allow-list and validate the chosen value separately before routing, identity or billing decisions.
Log minimally and prove one bounded request
Log the request identifiers, selected prefix, returned names and the specific approved value needed by the dialplan. Avoid dumping every header: Authorization, asserted identity, routing data, telephone numbers and vendor fields can be sensitive.
Correlate the result with one sanitized protocol trace on an authorized test path, then test a request without the optional field and an unrelated endpoint. Remove temporary logging and keep packet evidence under the deployment retention policy. This guide is documentation-derived; no PBX, header inventory or call was tested.
[from-example]
exten => _X.,1,Set(INBOUND_X_NAMES=${PJSIP_HEADERS(X-)})
same => n,Set(INBOUND_ROUTE=${PJSIP_HEADER(read,X-Example-Route,1)})
same => n,NoOp(Inbound custom names: ${INBOUND_X_NAMES})
same => n,Goto(route-policy,s,1)Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk PJSIP_HEADERS dialplan function ↗
- Asterisk PJSIP_HEADER dialplan function ↗
- Asterisk res_pjsip header-function source ↗
- RFC 3261: SIP Session Initiation Protocol ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.