Asterisk PJSIP contact qualification: read OPTIONS status correctly

Separate the endpoint, AoR and contact

An endpoint carries policy, an address of record groups reachable locations, and each contact is a concrete SIP URI. A dynamically registered phone can create a contact, while a trunk can use a configured contact without REGISTER. Inspect all three objects before treating one status label as the state of the whole service.

Use the running object inventory. Confirm the intended endpoint points to the expected AoR, then record every current contact URI, expiration and transport path. A saved configuration file does not prove that a contact loaded or that a registration remains current.

Understand what qualification measures

Asterisk sends SIP OPTIONS to a contact when qualify_frequency is non-zero. The current reference documents a default frequency of zero, which means no periodic qualification, and a default qualify_timeout of three seconds when qualification is enabled. DNS lookup time is included in that timeout; zero disables the timeout rather than making a three-second measurement.

A reachable result establishes that the configured qualification transaction received an acceptable response in time. It does not authenticate every later INVITE, validate the dialed destination, negotiate media or prove that an application behind a proxy is healthy.

Treat accepted response policy as version-sensitive

By default, contact availability is not limited to 2xx responses. Asterisk added qualify_2xx_only in 20.12.0, 21.7.0 and 22.2.0. Confirm the installed branch and maintenance release before expecting the option. Enabling it changes which OPTIONS responses count as available, but it does not turn OPTIONS into a call test.

Current documentation also says Asterisk completes a qualification authentication challenge regardless of the legacy authenticate_qualify value. Preserve the received response and full exchange instead of reasoning from an option name that no longer changes that behavior.

Read each event schema literally

Asterisk 22's ContactStatus change event uses Unknown, Unreachable, Reachable, Unqualified, Removed and Updated. Its ContactStatusDetail snapshot schema instead lists Reachable, Unreachable, NonQualified and Unknown, then adds registration expiry, Via address, Call-ID, Path, user agent and qualification settings. Those labels belong to different event fields and should not be normalized into an invented universal state.

Record the event type, field name, AoR, contact URI, endpoint name, timestamp and round-trip value together. Removed or Updated is a lifecycle event, while Reachable or Unreachable is a qualification observation. A detail snapshot and a later state-change event can both be correct at different moments.

Correlate timeout, DNS, proxy and response

Record qualification frequency, timeout, outbound proxy, resolved destination and observation time. Because DNS lookup is part of the timeout, an Unreachable transition can occur before a SIP request is sent. A proxy can also answer OPTIONS while the registered user agent or downstream application is unavailable.

Use one bounded PJSIPQualify action only when an immediate observation is authorized; it targets an endpoint and does not rewrite the periodic policy. PJSIPShowContacts produces a contact inventory and completion event, which is a snapshot rather than a continuous service monitor.

Prove call behavior separately

After qualification is understood, place one authorized call and follow the INVITE, final SIP response, SDP and media. A contact can answer OPTIONS while rejecting or misrouting INVITE, and it can complete signaling while RTP fails. Use the focused reachable-contact troubleshooting path for that boundary.

Record the installed Asterisk branch, maintenance release and loaded settings before and after any change. Retest one success and one expected rejection, then restore the previous frequency, timeout or response policy if the change creates false availability or unnecessary traffic. No endpoint, PBX, DNS path, proxy, OPTIONS exchange, event stream, call or media result was inspected or tested for this guide.

pjsip show endpoints
pjsip show aor office-aor
pjsip show contacts
pjsip show contact office-aor/sip:device@example.invalid

Keep qualification fields attached to one contact identifier

The AoR/contact inspection guide keeps status and RTT scoped to one contact and does not convert OPTIONS evidence into call success or media quality.

Keep registration expiry separate from qualification state

The AMI inbound-registration guide treats RegExpire and ContactStatusDetail reachability as different evidence.

Keep endpoint device state separate from contact qualification

The AMI endpoint inventory guide treats aggregate DeviceState and contact reachability as different observations.

Do not turn AoR qualification policy into observed reachability

The AMI AoR inventory guide separates configured frequency, timeout and response policy from an actual OPTIONS result.