Keep the recording target and name explicit
ARI can start a recording on a channel or a bridge. Preserve the application operation ID, running Asterisk branch, Stasis application, target URI, application-owned recording name, format, start parameters and request timestamp. The recording name identifies the live control object and later stored resource; it is not a generic call ID or an arbitrary filesystem path.
Choose collision-resistant names and define retry behavior before sending the request. The documented ifExists choices are fail, overwrite and append; an in-progress recording or fail policy can return 409. Do not make a retry destructive by changing to overwrite without proving which operation owns the existing name.
Choose channel or bridge scope deliberately
A channel recording captures audio from that channel and the Channels API explicitly says it does not capture audio sent to the channel. A bridge recording captures the mixed audio from channels participating in that bridge. A valid channel recording can therefore contain only one direction, while a bridge recording can omit a participant that was not a member during the recording window.
Record bridge membership and channel lifecycle during the requested interval. Do not infer two-way coverage from a nonzero file, a successful start response or the fact that two parties were connected elsewhere in the call graph.
Separate live state from stored-file state
ARI distinguishes LiveRecording from StoredRecording. A live object exposes its name, format, target URI, state and optional duration, silence, talking and failure fields. The documented states include queued, recording, paused, done, failed and canceled. A stored object is the completed name-and-format resource that can be listed, retrieved, copied, deleted or played back.
Asterisk stores completed ARI recordings under the recording subdirectory of the configured astspooldir; the documented default is /var/spool/asterisk/recording. Inventory visibility, file readability, retention ownership and downstream export remain separate from the live control lifecycle.
Correlate response, events and current resource
Retain the HTTP response together with RecordingStarted, RecordingFinished and RecordingFailed events for the exact name. The REST and WebSocket paths are asynchronous; an accepted request, event and current resource snapshot answer different questions. Reconnect or process restart can create an event gap without deleting the server-side object.
Reconcile by recording name before retrying, stopping or beginning a new operation. A finished event reports completion of the recording operation, not file readability, both call directions, participant notice or useful decoded speech.
Treat pause, mute, stop and cancel as different outcomes
Pause and mute act on a live recording, but they do not carry the same intent. The Asterisk 22 API states that both suspend silence detection; paused time is excluded from maxDurationSeconds. Preserve the control timestamp, response, state before and after, and any concurrent maximum-duration or silence limit.
Stopping stores the recording. Canceling stops and discards it. Make cleanup idempotent and tolerate 404 when a named live recording no longer exists or 409 when a pause or mute operation is not valid in the current session. Do not issue cancel as a generic substitute for stop.
Keep duration, silence and content evidence distinct
maxDurationSeconds, maxSilenceSeconds, beep and terminateOn are start-time controls. Zero means no limit for the two maximums; terminateOn can be none, any, star or pound. A pause or mute changes silence accounting, so a short result must be interpreted with the retained control timeline rather than only the final duration.
After storage, verify the expected format, readable file, bounded duration and authorized decoded sample. File existence or size does not prove that the intended talker was captured, that both directions are present, that speech is intelligible or that the business interval is complete.
Apply security, notice and retention outside the media API
Use HTTPS and WSS for ARI, a restricted ARI identity and input validation for target IDs, names and formats. Keep recordings outside public web roots, protect exports, define retention and deletion, and remove temporary diagnostic copies. The API can create or retrieve media; it does not establish recording authorization, participant notice, jurisdictional compliance or access policy.
Pilot with synthetic or otherwise authorized calls, exercise stop, cancel, pause, mute, collision and restart paths, and preserve both application and stored-resource evidence. No recording or call was tested for this guide.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk ARI Recording API guide ↗
- Asterisk 22 ARI Recordings REST API ↗
- Certified Asterisk 22.8 ARI Channels REST API ↗
- Asterisk latest ARI Bridges REST API ↗
- Asterisk 22 ARI REST data models ↗
- Asterisk configuration for ARI ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.