Freeze one mailbox and classify the disagreement
Record the exact mailbox name and case, encoded request path, external source revision, expected new and old counts, Asterisk version, loaded voicemail-state provider, ARI user, request timestamp and response, immediate GET, restart history, downstream mailbox mapping, NOTIFY evidence and final endpoint display.
Classify the symptom before changing anything: the state is absent, PUT is rejected, read-back differs immediately, the count becomes stale later, restart changes it, Asterisk is correct but SIP delivery differs, or the endpoint received the right body but renders another indication. Those failures have different owners.
Prove one supported mailbox-state provider
Confirm that the deployment intentionally uses the external-MWI architecture and the expected res_mwi_external support. Asterisk warns that this provider and app_voicemail are mutually exclusive. If app_voicemail owns the local mailbox, stop writing parallel ARI counts and investigate its message store or supported refresh mechanism instead.
For external ownership, verify the Sorcery mapping and authoritative application without assuming the presence of a module file proves it is loaded, configured or writing the observed state. Do not unload a voicemail provider or clear mailboxes during an incident merely to remove the disagreement.
Validate the exact request and immediate read-back
Use the case-sensitive mailbox name and send both required query values, oldMessages and newMessages, as absolute counts. Preserve authentication and authorization failures separately from 404 for an absent GET or DELETE target. A read-only ARI user can inspect with GET but cannot establish that a PUT was accepted.
After the update, GET the same exact name and compare all fields. If it is already wrong, stay with request construction, provider ownership or a competing writer. If it is correct, stop retrying and move to later overwrite, persistence or consumer delivery.
Find competing writers and restart drift
Correlate every integration instance that can publish the mailbox. Look for a stale worker, retry queue, startup snapshot, delayed webhook or cleanup job that wrote an older absolute state after the good update. ARI exposes the current name and counts, not writer identity or a compare-and-swap revision, so concurrency control belongs in the external application.
Compare pre-restart state, configured Sorcery backend, source availability during startup and the first reconciliation. Do not translate a source timeout into zero messages or republish a cached snapshot without a freshness rule.
Follow correct counts into the MWI consumer path
Once ARI read-back is correct and stable, confirm that the PJSIP endpoint or AOR refers to the same mailbox name and that the deployment intentionally uses subscribed or unsolicited MWI. Preserve loaded modules, subscription state where applicable, generated application/simple-message-summary body, destination contact, SIP response and endpoint account selection.
A 200 response to NOTIFY does not prove a lamp changed, while a stale lamp does not justify falsifying ARI counts. Use the focused PJSIP MWI investigation for that downstream chain.
Correct one owner and prove the full lifecycle
Correct only the demonstrated owner: external source mapping, mailbox name, request fields, ARI write permission, competing publisher, startup reconciliation, persistence mapping, PJSIP mailbox mapping, subscription model or endpoint interpretation. Keep the prior configuration and a rollback trigger.
Publish a controlled nonzero new count, confirm immediate and delayed read-back, observe the expected downstream notification, then clear or age the count according to the external system and repeat after restart. Test a neighboring mailbox as a control. Remove temporary traces and redact message metadata and credentials. No host, mailbox, message, endpoint, lamp or notification was tested for this diagnostic.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk 22 ARI Mailboxes REST API ↗
- Asterisk 22 ARI REST data models ↗
- Certified Asterisk 22.8 res_mwi_external configuration ↗
- Asterisk message-waiting indication guidance ↗
- Asterisk configuration for ARI ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.