Asterisk ARI mailboxes: external MWI state, ownership and lifecycle

Treat the ARI mailbox as count state, not a message store

The ARI Mailbox model contains a name plus new- and old-message counts. It does not contain recordings, message identifiers, callers, timestamps, folders, greetings, retrieval credentials or retention policy. GET /mailboxes lists the mailbox states visible through this resource, while GET /mailboxes/{mailboxName} retrieves one exact case-sensitive name.

Define the external voicemail system that owns each name and the rule that maps its folders or read status into Asterisk's two counts. A successful GET proves only the state currently exposed by Asterisk. It does not prove that a recording exists, a user can retrieve it, a phone received a notification or a lamp changed.

Keep external-MWI ownership separate from app_voicemail

Asterisk documents res_mwi_external as the core for externally supplied MWI and provides a persistent mailbox cache whose Sorcery backend mapping can be altered. Its MWI guidance warns that the external-MWI module and app_voicemail are mutually exclusive. Choose the voicemail-state provider deliberately rather than writing ARI counts over locally owned app_voicemail mailboxes.

Record the loaded modules, authoritative store, mailbox namespace, persistence mapping, restart owner and consumer configuration. If an external program merely changes files or database rows belonging to app_voicemail, use that application's supported refresh path instead of creating a second authority through ARI.

Use PUT as an absolute, idempotent state replacement

PUT /mailboxes/{mailboxName} requires both oldMessages and newMessages, changes the state and implicitly creates the mailbox. Send the authoritative absolute counts after validating that they are non-negative and belong to the exact mailbox; do not treat PUT as an increment operation or retry by adding the same delta again.

Give one integration ownership of each mailbox or apply a durable version and conflict policy outside ARI. Retain the source revision, requested counts, HTTP result and immediate GET. A later successful write can legitimately replace an earlier value, so a 204-style success by itself is not evidence that the value remained current.

Define restart and persistence reconciliation

The module documentation describes a persistent cache and configurable Sorcery mapping, but that does not establish the backend, durability or recovery point on a particular host. On startup, enumerate the states Asterisk exposes, compare them with the external system's authoritative snapshot and publish deliberate corrections. Mark the integration unhealthy when the source is unavailable instead of clearing every mailbox to zero.

Test restart, delayed source recovery, duplicate delivery and an update arriving during reconciliation. Keep clock, source revision and writer identity in application logs; the ARI Mailbox model itself exposes counts and name, not an application transaction version.

Separate stored state from PJSIP delivery and display

An ARI read-back with the expected counts establishes the Asterisk mailbox-state layer. PJSIP subscription or unsolicited MWI configuration, loaded MWI modules, generated message-summary content, SIP delivery and endpoint rendering remain separate. An endpoint can show the wrong lamp even when ARI state is correct, and a correct lamp does not prove a user can retrieve the expected messages.

Preserve the mailbox name used by the consumer, the chosen solicited or unsolicited model, the NOTIFY body and response, and the final endpoint behavior. Continue with the Asterisk PJSIP MWI diagnostic only after proving the external count source.

Delete state only at the end of a controlled lifecycle

DELETE /mailboxes/{mailboxName} destroys the ARI mailbox state and returns 404 when the named state is absent. It does not delete recordings from an external voicemail platform. Remove state only after the authoritative mailbox has been retired, writers are stopped and every PJSIP or application consumer has a defined missing-mailbox behavior.

Restrict ARI write access, network reachability and mailbox namespaces. Use HTTPS where supported, keep credentials out of URLs and logs, and put browser-facing tools behind an application authorization layer. Acceptance covers create or update, read-back, downstream notification, count clear, restart reconciliation and controlled deletion. No mailbox, message, endpoint or live notification was tested for this guide.

Keep ARI and AMI external state ownership explicit

The AMI MWI control guide separates res_mwi_external_ami count state, remote synchronization and ARI mailbox lifecycle.