Asterisk PJSIP: understand the configuration objects

Map the relationships first

An endpoint defines call-related behavior such as codecs and the incoming dialplan context. An auth object supplies authentication settings. An Address of Record, or AOR, represents how Asterisk can contact an endpoint. A transport defines a signaling listener or connection transport. These objects cooperate but solve different problems.

Outbound registration is a separate relationship: it tells another registrar where Asterisk can be reached. It does not automatically create an endpoint, an incoming call identity rule or a safe dialplan.

PJSIP endpoint, auth and AOR

Build a configuration inventory

For each phone, record the endpoint name, auth reference, AOR reference and context. For each trunk, also record how incoming requests are matched and whether outbound registration is required. Keep credentials outside shared troubleshooting notes.

An object can exist in a file yet fail to load because of a syntax error, unsupported setting or unresolved relationship. Check what the running engine actually loaded instead of assuming a saved file is active.

The global identifier order and an endpoint’s identify_by list answer different questions. Review the endpoint-identification guide before changing either control.

Contact qualification is an AOR-level reachability control. Review the contact qualification guide before interpreting an OPTIONS status as endpoint or call health.

When a call ends with 480, use the focused unavailable diagnosis to distinguish a received response from local contact or dialplan state before changing the endpoint.

Start an unidentified-request incident at the matching boundary

If the console says an inbound request could not be identified, follow the endpoint-matching diagnosis before changing auth, inbound routes or media. It proves the loaded identifier modules, global order, endpoint identify_by permission and exact request field, then tests that an unrelated request remains rejected.

Inspect before changing

Use pjsip show endpoints to see endpoint state, then inspect the relevant endpoint and AOR. A contact address answers where requests may be sent; a successful qualify response indicates a response to that probe, not a complete successful business call.

If the endpoint exists but calls fail, follow the incoming context and dialed extension. If it does not exist, investigate configuration loading first. This ordering prevents routing edits from obscuring a configuration problem.

pjsip show endpoints
pjsip show endpoint 2101
pjsip show aor 2101
pjsip show contacts

Apply with the right lifecycle

Some changes can be reloaded; transport changes can require a restart depending on configuration and support. Schedule disruptive work and consult the exact version's reference. In FreePBX, use its supported interface and apply mechanism rather than editing generated files directly.

When a transport edit does not appear in the running system, follow the transport activation investigation rather than repeating a generic reload.

Distinguish a loaded transport from a bound and selected path

The refreshed transport activation investigation compares the saved object, loaded PJSIP view, operating-system listener and the consumer's selected transport. It checks conflicting address/protocol/port tuples before a controlled restart and does not treat allow_reload, a visible listener or a successful Apply Config action as proof that an endpoint or registration uses the intended path.

Treat repeated authentication as a relationship problem

A 401 or 407 challenge can be expected; the result depends on the matched endpoint or registration, referenced auth object, realm, allowed digest algorithms and usable credential form. The PJSIP authentication-loop guide follows those layers and includes the Asterisk 22.2 algorithm boundary.

Separate the two expiration policies

A registration object's expiration controls what Asterisk requests as an outbound client. An AOR's minimum_expiration and maximum_expiration constrain dynamic contacts when Asterisk acts as registrar. The SIP 423 diagnostic begins by identifying which role produced the rejection.

Keep call session timers separate from registration expiry

A SIP 422 response concerns RFC 4028 session-timer negotiation on an INVITE or UPDATE, not a REGISTER lifetime, qualify interval or RTP inactivity timeout. Preserve Session-Expires, Min-SE, the timer option tag, refresher role and the exact PJSIP leg before changing an endpoint. The focused 422 investigation maps those fields to the loaded timers, timers_min_se and timers_sess_expires controls.

Separate 491 recovery from its request trigger

SIP 491 reports a same-dialog pending-request or offer collision; it is not a busy response. Preserve the outstanding re-INVITE or offer, the rejected re-INVITE or UPDATE, Call-ID ownership, retry delay and new transaction on the exact PJSIP leg. The focused glare investigation maps those messages to the loaded direct_media, direct_media_method, direct_media_glare_mitigation and connected_line_method controls without treating one option as a universal retry switch.

Recognize the maintenance-mode version boundary

Asterisk documents PJSIP endpoint maintenance mode from 22.10.0 in the 22 LTS branch. New out-of-dialog inbound requests can receive 503 while outbound originations are refused before channel creation. Use the 503 investigation to distinguish that intentional state from a remote response or a different local failure.

Assign the TLS verification role

For an inbound phone connection, Asterisk presents its transport certificate while the phone normally decides whether to trust the PBX identity. For an outbound TLS connection, Asterisk can verify the remote server through its CA and server-verification controls. The PJSIP TLS certificate investigation keeps those roles, client-certificate policy and post-handshake SIP authentication separate.

Separate SIP body rejection from SDP negotiation

SIP 415 concerns the request body format, language, encoding or required body disposition in the method's context; it is not the generic code for an unacceptable codec offer. Preserve the request method, Content-Type, Content-Disposition, Content-Encoding and multipart boundaries before changing endpoint codec policy. Use the focused 415 investigation to identify the responder and exact body part.

Preserve a 600 before translating it to busy

SIP 600 asserts global busy state, while Asterisk maps both 600 and the contact-local 486 response to AST_CAUSE_USER_BUSY, Q.850 cause 17. Preserve the exact response, responder, PJSIP channel and all forked branch outcomes before relying on DIALSTATUS=BUSY or another translated label. The focused 600 investigation keeps endpoint, provider, dialplan and voicemail policy boundaries explicit.

Preserve a 603 before interpreting call rejection

SIP 603 is a global decline response, but Asterisk maps it with 401, 403 and 407 to the shared call-rejected cause. Preserve the exact response, responder and PJSIP channel before using the translated cause or dialplan result. The focused 603 investigation separates a received decline from a deliberate local final response and an upstream policy choice.

Preserve a 604 before treating a user as unallocated

SIP 604 is an authoritative global assertion about the user in one exact Request-URI, while Asterisk maps it with 404 and 485 to AST_CAUSE_UNALLOCATED, Q.850 cause 1. Preserve the wire response, responder, URI, PJSIP channel and any cancelled branches before acting on the translated cause. The focused 604 investigation separates normalization, namespace authority and per-channel evidence.

Preserve a 606 before changing media policy

SIP 606 is a global session-description rejection from a successfully contacted user agent, while Asterisk maps it with resource-local 488 to AST_CAUSE_BEARERCAPABILITY_NOTAVAIL, Q.850 cause 58. Preserve the offer, exact response, responder, Warning fields, fork scope and PJSIP channel before changing codecs, addressing or security. The focused 606 investigation keeps the global scope, session mismatch and coarser cause translation separate.

Separate an unsupported event package from its body format

A SIP 489 response says that the responding notifier did not understand the event package in the Event header. It does not by itself show that the target resource, authorization, Accept formats or later NOTIFY delivery were tested. The focused 489 investigation checks the exact PJSIP leg, loaded pubsub core and package-specific handler without treating every subscription failure as missing presence support.

Keep Identity generation separate from caller-ID display

A SIP 428 response means the verifier could not use any Identity header and its local policy required one; it is not a generic caller-ID mismatch or reputation verdict. Asterisk's refactored STIR/SHAKEN service associates an effective profile with a PJSIP endpoint and uses the channel caller ID, configured TN, signing key, public-certificate URL and attestation level when it generates an outgoing Identity header. The focused 428 investigation checks the exact release, profile, caller-ID source and wire request before any header or policy change.

Separate certificate retrieval from certificate acceptance

SIP 436 means the verifier could not acquire credentials for any Identity field; it is distinct from acquiring a credential that the verifier does not support or trust, and from validating a bad signature. The focused 436 investigation follows Asterisk's active verification profile, x5u policy, certificate cache and retrieval evidence without weakening URL controls or treating a reachable certificate as trusted.

Prove credential support after retrieval

SIP 437 begins only after at least one Identity credential has been acquired or is already held. It reports that the verifier cannot support the available credential, including an untrusted issuing CA or unsupported credential-signing algorithm; it is not a fetch failure or proof of a bad PASSporT signature. The focused 437 investigation follows the active Asterisk trust store, chain and release-specific certificate tooling before any CA or algorithm change.

Reconstruct the PASSporT before assigning 438

SIP 438 means that none of the request's Identity fields contains a valid supported PASSporT under the rejecting verifier's policy. It can reflect a bad signature or required claim, but transit mutation such as a changed Date value can also break compact-form reconstruction; it is not automatic proof of spoofing. The focused 438 investigation preserves the exact request, all Identity fields, active Asterisk profile and per-identity verification results before a bounded repair.

Separate inbound and outbound authentication

Use the digest-authentication guide to distinguish an endpoint's inbound auth object from an endpoint or registration's outbound_auth relationship. Realm matching, supported algorithm policy and available plaintext or pre-computed credential material must agree on the running build; a normal 401 or 407 challenge is not itself a failed login.

Keep subscription delivery outside the hint

A loaded hint does not prove that res_pjsip accepted a phone's SUBSCRIBE or generated a body the phone understands. The device-state and hints guide preserves endpoint identification, allow_subscribe, context, Event and Accept values, response, dialog and NOTIFY bodies before assigning a BLF fault. Use the BLF update diagnosis to classify rejection, missing notification, rejected body and accepted-but-misrendered state without changing every layer together.

Do not confuse overload admission control with the alerting queue

The taskprocessor overload diagnosis distinguishes the taskprocessor that crossed its water mark from res_pjsip's configured response. With the documented default global trigger, a queue outside PJSIP can cause the distributor to stop accepting new SIP requests until alerts clear; that does not turn the original queue into a PJSIP queue or justify disabling protection.

An AoR contact is a live routing destination

Use the AoR and contacts guide to distinguish configured policy from dynamic REGISTER bindings, qualification observations and the dial string that selects one or all contacts.

Qualification events have versioned vocabularies

The refreshed PJSIP contact-qualification guide distinguishes periodic OPTIONS policy, DNS-inclusive timeout, branch-specific qualify_2xx_only availability and the different status vocabularies used by change and detail events.

Do not infer the sent transport from an object name

Use the transport-selection guide to follow the effective URI through SRV resolution, address family, explicit or first-valid local transport and live TCP or TLS connection reuse. The focused diagnostic keeps REGISTER, OPTIONS and INVITE owners separate.

Treat session timers as endpoint policy plus dialog evidence

A PJSIP endpoint exposes timer policy, but the live dialog owns its accepted Session-Expires interval and refresher. Use the session-timer guide and the drop diagnostic to correlate those layers without changing registration or RTP clocks.

Treat direct media as a negotiated per-call result

Endpoint direct_media policy does not prove where one call sent RTP. Use the direct-media guide to follow the exact channel legs, mid-dialog offer/answer, bridge state and final packet path.

Treat DTMF as per-leg policy and evidence

The PJSIP DTMF guide maps rfc4733, inband, info, auto, auto_info and none to the actual offer, event, request or audio path on each endpoint. A correct ingress digit does not establish the representation sent on the egress leg.

Keep 100rel policy separate from media success

A loaded endpoint's 100rel mode governs reliable provisional-response signaling. The early-media and PRACK guide shows why a matching PRACK does not prove accepted SDP, arriving RTP or audible ringback.

Do not confuse the allow list with the negotiated codec

Use the codec-negotiation guide to follow incoming offer, outgoing offer, incoming answer and outgoing answer independently. A configured order is only one input.

Treat PJSIP NAT controls as distinct runtime decisions

The media-address and NAT guide keeps media_address, bind_rtp_to_media_address, external_media_address, rtp_symmetric, force_rport and rewrite_contact tied to their separate SDP, RTP and SIP roles.

Use the PJSIP object graph when retiring chan_sip

The FreePBX trunk migration guide applies Asterisk's migration model without treating its basic conversion script as a FreePBX import. It verifies registration, auth, AOR, endpoint, identify and transport ownership separately.

Prove the STIR/SHAKEN effective profile on each endpoint

A PJSIP endpoint can select a STIR/SHAKEN profile, but the result also depends on the global attestation or verification object and any TN-specific settings. Use the STIR/SHAKEN operations guide to inspect the effective profile and the exact INVITE rather than treating stir_shaken_profile as a complete policy.

Keep registration Contact and calling identity separate

Asterisk 22 gives outbound registration its own client_uri, server_uri, contact_user, transport, outbound_proxy and outbound_auth controls. Endpoint from_user and contact_user affect different request fields. The refreshed 403 diagnostic applies that separation to CompanyFlex without presenting another account's values as a template.

Keep DNS candidates separate from loaded PJSIP state

The PJSIP DNS-resolution guide follows a hostname through the effective URI, resolver and SRV or address answers before transport and registration state. A DNS edit does not itself reload an object, close a connection or restart a stopped registration.

Match PJSIP transport objects to address family

For dual stack, follow the IPv4 and IPv6 transport guide instead of assuming one wildcard listener covers both families. The loaded transport, real socket and selected destination must agree.

Inspect endpoint-identification state as four separate views

The refreshed endpoint-identification guide separates registered identifier mechanisms, effective global order, loaded identify objects and each endpoint's permitted methods. The unidentified-request diagnostic then binds those views to one request and a negative control before authentication, routing or media changes.

Keep source and Contact ACLs distinct

PJSIP source rules evaluate the packet address, while Contact rules evaluate advertised Contact addresses in incoming REGISTER requests. The ACL boundary guide shows where module-wide, endpoint and named controls differ.

Treat a custom header as channel-scoped state

An inbound header, caller variable and outbound PJSIP request are different evidence. Use the outbound-header guide to choose a callee pre-dial write or a version-supported inheritable header and then verify the wire request.

Keep dialplan media offers channel-scoped

Use the PJSIP_MEDIA_OFFER workflow when one outbound PJSIP leg needs a bounded codec-list change. The caller, each callee, endpoint policy and later session refresh remain separate evidence.

Keep parsed URI fields separate from PJSIP object selection

Use the PJSIP URI parser guide to extract documented parts while preserving endpoint identification, authentication, DNS, transport and route ownership as later decisions.

Keep response data on the outbound PJSIP channel

Use the PJSIP response-header guide to read the answered INVITE response from its callee channel without confusing request headers, caller variables or provisional messages.

Read AoR and contact fields as separate PJSIP objects

Use the AoR and contact inspection guide to preserve endpoint, AoR, contact identifier, URI, lifecycle and qualification scope.

Read endpoint configuration from the channel that owns the behavior

Use the PJSIP endpoint inspection guide to distinguish the endpoint profile from inbound identification, AoR location, contact inventory and negotiated session state.

Treat DTMF mode as channel-scoped runtime state

Use the PJSIP_DTMF_MODE guide to keep endpoint policy, caller and callee ownership, RFC 4733, SIP INFO, in-band tones and the IVR result as separate evidence.

Assign REFER ownership on the exact PJSIP channel

Use the PJSIP_TRANSFER_HANDLING guide to distinguish default core handling from ARI-only event ownership without treating a 202 response as transfer completion.

Keep From URI and header parameters on the exact channel

Use the PJSIP_HEADER_PARAM workflow to write a documented parameter on one outbound callee without treating syntax as identity acceptance.

Choose the exact NOTIFY target and content owner

Use the PJSIP NOTIFY guide to distinguish an endpoint, arbitrary URI and live dialog while keeping a SIP response separate from the device action.

Keep runtime registration control scoped to one object

Use the PJSIPRegister and PJSIPUnregister guide to avoid confusing an outbound-registration object with its endpoint, trunk or provider account.

Use the new inheritable-header function only on supported branches

Asterisk documents PJSIP_INHERITABLE_HEADER() from 20.19.0, 22.9.0 and 23.3.0. The version-sensitive guide preserves those floors and the caller-to-callee ownership boundary.

Treat session refresh as one channel-scoped transaction

Use the session-refresh guide to keep the current channel, selected method, SDP exchange and media result visible.

Keep inbound name discovery separate from outbound mutation

Use the PJSIP inbound-header inventory guide for names on the current INVITE, then read the intended inbound instance without treating the list as proof of a future outbound request.

Keep PJSIP hold policy attached to the active leg

Use the MOH passthrough guide to distinguish an endpoint default from the effective per-call value, peer-facing re-INVITE and final media owner.

Own the incoming transaction before selecting its final response

PJSIPHangup() can return one explicit final response only on the incoming PJSIP channel and before another final response. The guide preserves transaction, channel and mapping evidence instead of treating a cause code as the wire result.

Keep PJSIP channel context leg-specific

CHANNEL(pjsip,...) reports signaling data for the current PJSIP leg. The guide prevents caller, callee, Local-channel and bridge-peer evidence from being merged.

Keep PJSIP signaling and RTP selectors separate

Use the signaling-context guide for dialog and SIP socket evidence, then the RTP-context guide for one audio or video stream.

Keep PJSIP MESSAGE routing and identity separate

Use the MessageSend guide to distinguish the destination-derived Request-URI from To and From headers, endpoint policy, AoR and current contact.

Use PJSIP History as a bounded evidence store

The PJSIP History guide shows how to retain and filter one approved signaling interval without treating the capture as permanent monitoring.

Keep the CommPeak PJSIP and chan_sip examples distinct

CommPeak's FreePBX guide uses chan_pjsip, while its standalone Asterisk example edits sip.conf and uses sip commands. The provider record treats these as version-specific examples rather than interchangeable configuration.

Separate PJSIP object storage from runtime state

The PJSIP Realtime guide keeps database rows, loaded objects, contacts, identification, registrations and calls as different observations.

Model each Voximplant SIP relationship as its own PJSIP object path

The Voximplant provider record keeps allowlisted ingress, user registration and authenticated outbound SIP distinct so endpoint, identify, auth, AoR and registration objects are not invented or merged.

Do not infer loaded PJSIP objects from file content

The AMI configuration diagnostic continues from the written file through module reload and exact loaded objects.

Keep res_pjsip load state separate from PJSIP objects

The module capability diagnostic does not infer endpoints, transports or registrations from a loaded module row.

Map AMI registration rows to PJSIP objects

The AMI inbound-registration guide keeps endpoints, AoRs, static contacts and REGISTER-created contacts distinct.

Map endpoint-list rows back to loaded PJSIP objects

The AMI endpoint inventory guide keeps endpoint, AoR, auth, transport, identify and contact evidence distinct.