Secure AI actions and human handoff with Asterisk
A voice agent can suggest an action, but the application connected to Asterisk must decide whether it is allowed. Keep business-system credentials and call-control authority on a trusted server. Check each request against the caller's verified session, the call's current state and a small allowlist of actions.
Source-reviewed, 20 October 2026. This guide combines Asterisk ARI channel-control documentation with current provider tool/delegation contracts. Phone Guides has not executed an AI tool call or transfer on an Asterisk system. The examples are design checks, not a tested FreePBX recipe. FreePBX support for a custom ARI application depends on the exact release and supported extension point.
For dated provider SDK/API versions, audio and session limits, lifecycle events, pricing and data terms, see the Asterisk AI provider contract checklist.
Separate suggestion, authorization and execution
Treat the model's tool request as untrusted input, even when its schema is valid or the provider marks the function call complete. A schema can restrict the shape of an argument; it cannot establish caller identity, ownership of a customer record, permission to disclose it, or authority to transfer a call.
Use three owners:
| Owner | Responsibility |
|---|---|
| Voice model | Understand the request and suggest a named action with arguments. It has no business credential or unrestricted PBX access. |
| Application server | Validate the call and caller context, check policy and confirmation requirements, authorize a narrow action, call the business API, save an outcome and decide what result can be spoken. |
| Asterisk ARI application | Own channel and bridge state, media resources, DTMF, call timeout, transfer and cleanup while the channel is in its Stasis application. |
Keep the action list short. Prefer read-only lookup before changes. Split actions by purpose: check_order_status should not accept an order number and arbitrary API path; request_human_transfer should not accept any destination supplied by the model. Resolve records and permitted transfer targets on the server from authenticated application state.
Bind an action to a live, authorized call
Before executing a request, validate a server-created call record rather than trusting identifiers from the model. Record an opaque internal call/session ID, the Asterisk channel ID, the provider session ID, the authenticated caller or account context, the allowed task, and the current call state. Do not use caller ID alone as proof of identity.
For each tool request:
- Confirm that the provider session and ARI channel still belong to the active call record.
- Check that the channel is in the expected state and that the caller has completed any required authentication.
- Validate every argument against application rules and the authenticated caller's record-level access.
- Apply a separate confirmation step for a consequential or hard-to-reverse action. A spoken “yes” must be bound to the exact action and details being confirmed; use stronger authentication where the service requires it.
- Apply a short-lived idempotency key and store the request/result state before retrying. Do not repeat a payment, booking, account change or other side effect because a WebSocket reconnect or model retry repeated a tool call.
- Return only the minimum result needed for the conversation. Keep credentials, full records and unnecessary personal data out of model context and routine logs.
These are application design controls, not guarantees supplied by the voice API. OpenAI says its application executes custom functions and checks permissions and required confirmations; its migration guidance also says to preserve authorization, confirmation and input/output checks. Deepgram exposes client function-call and cancellation events under its own protocol. Its 8 September 2026 changelog says functions dispatch before turn confirmation by default; set defer_until_eot: true on each function that must wait. When FunctionCallCancelled names a client-side call, stop work for that ID and send no FunctionCallResponse. Microsoft Voice Live's parallel_tool_calls setting defaults to true; set it to false when one session must issue tool calls sequentially, but keep server-side action locks and idempotency because model sequencing is not a transaction guarantee. For ElevenLabs SIP, transfer_to_number can use SIP REFER only when the trunk permits it; SIP REFER transfers do not support a warm message to the receiving person. Restrict transfer destinations to an approved list and confirm that the target PBX accepts and routes REFER as intended. These provider contracts differ, so translate each into the same server-side authorization rules rather than treating event names as interchangeable. A provider cancellation or ordering choice does not roll back a request already submitted to a business service.
Handle interruption and cancellation as separate state
A caller can interrupt speech while backend work is pending. Stop or flush queued audio when appropriate, mark the conversation task as changed or cancelled, and check whether the action itself has started. Stopping generated speech does not reverse an accepted business request. A provider cancellation event does not prove a remote system cancelled its transaction.
Use an application state record such as:
| State | Meaning and next check |
|---|---|
proposed |
Model suggested an action. Nothing external has happened. Validate identity, scope and arguments. |
awaiting_confirmation |
Application is presenting the exact action and details for caller approval. Expire this state if the call or task changes. |
authorized |
Required checks passed. Create the idempotency record before the side effect. |
running |
Server has submitted the request. Track its downstream request ID and cancellation capability. |
completed |
Downstream system confirmed the result. Verify the result before describing it as complete. |
cancel_requested |
Caller changed or cancelled the task. Ask the downstream service to cancel if supported, then read back its actual status. |
rejected, failed or unknown |
No success is confirmed. Do not retry a non-idempotent action blindly; route to a person or explain the bounded next step. |
For an action with a compensation path, record how to request it and who may approve it. A compensating change is a new action; it is not proof that the original request never occurred.
Keep ARI call control on the application server
Asterisk uses the Stasis() dialplan application to hand an eligible channel to an ARI application. ARI generally controls channels placed in that Stasis application; it is not a general-purpose remote dialplan editor. The ARI application should make transfer decisions from its own call state and resolve destinations from an approved server-side list.
ARI's HTTP interface and event WebSocket are control connections. The AI media channel is a separate resource. Protect ARI with TLS/WSS where it crosses a network, a dedicated credential, network access controls and the applicable Asterisk security settings. Keep provider and business API secrets out of dialplan text, media frames, browser code and call recordings. Asterisk's user configuration includes a read_only setting; review the actual privileges required by the application and do not assume this alone creates fine-grained authorization for each business action.
When moving a caller to a human destination, the application should:
- Confirm the caller is still on the expected channel and the destination is in the permitted queue/extension map.
- Stop new AI tool execution for the old task and mark pending results as stale.
- Stop or flush AI playback, then remove or end the AI media leg according to the chosen bridge design.
- Move the caller through the ARI application's planned transfer path and observe the resulting channel/bridge events.
- If the destination cannot be reached, use the predefined queue, callback or service-message fallback. Never leave a caller connected to silent media.
- On caller hangup, close the provider session where possible, release bridges and external-media channels, and ignore late events tied to the ended call.
Asterisk documents bridge add/remove operations and StasisEnd channel lifecycle events. The exact transfer sequence depends on whether your application uses an ARI bridge, a dialplan continuation or another supported call path. Write and test the selected path for the target branch; do not copy an API sequence from a different bridge design.
Decide what callers hear when an action fails
| Condition | Application response |
|---|---|
| Caller is not authenticated for the requested record | Refuse the lookup and offer the approved authentication or human route. |
| Tool request names an unknown action or has invalid arguments | Reject it, record a non-sensitive reason and keep the call on the current safe route. |
| Caller interrupts before an action starts | Mark the task cancelled and discard its pending request. |
| Caller interrupts after submission | Check the downstream request status; cancel or compensate only through a documented operation and report what is actually known. |
| Provider disconnects during a tool action | Keep the application task state, query the downstream result if safe, and avoid replaying an uncertain side effect. |
| AI media or human transfer fails | Use the named fallback route and release stale media resources. |
| Call ends while a result is late | Do not send that result to a new call or resume the ended voice session. |
Keep a call trace useful without storing raw audio or full transcripts by default. Record the opaque call ID, action name, policy decision, downstream request ID, timestamps and final status. Set retention and access for these records separately from recordings and transcripts. The companion AI call data and operations checklist covers the broader data map.
Test with a fake business service before a real account
Use a local fake API and synthetic callers to check allowed and rejected actions, duplicate requests, stale provider events, interruption before and after submission, provider loss, call hangup and unavailable transfer targets. Assert both the spoken result and the fake service's final state. Confirm that a canceled request did not silently complete later, or record the unresolved outcome if the fake cannot model that boundary.
Then test the exact Asterisk branch, ARI application build, carrier path and endpoint with a private test route. Verify the media and control planes independently. A passing unit test does not prove carrier transfer, DTMF delivery, audio interruption or FreePBX support. Record versions and observed outcomes before describing the route as tested.
Sources and limits
- Asterisk ARI configuration: Stasis handoff, ARI HTTP/WebSocket configuration and user settings.
- Asterisk security considerations: network protections and dialplan authorization boundaries.
- ARI channel lifecycle and bridge operations: channel events and bridge changes.
- OpenAI GPT-Live delegation and tools: application-owned function execution, permission and confirmation checks, result handling and pending-work events.
- OpenAI server-side controls and migration guardrails: server-side tools, session steering and preserving existing authorization checks.
- Deepgram Voice Agent server events: provider-specific function-call and cancellation events.
- Deepgram deferred function calls and cancellation:
defer_until_eotdefaults to false; cancelled client-side calls must not receive aFunctionCallResponse. - [Microsoft Voice Live API reference
2026-07-15](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/voice-live-api-reference-2026-07-15): tool-call parallelism defaults to enabled; the application remains responsible for action authorization and duplicate-side-effect handling. - ElevenLabs transfer to number: SIP REFER requires trunk support, is the only SIP transfer type for SIP URI destinations, and does not carry a warm transfer message.
The provider documentation defines API events. It does not establish that Phone Guides' proposed server state machine or any adapter is running, that an action was authorised by a customer system, or that a specific FreePBX release supports this routing design. Confirm the exact API/model, PBX version and supported extension point before deployment.