Skip to content
Phone Guides

Live voice agents with Asterisk

A live voice agent needs a call-control application, an audio path and an adapter for the chosen AI service. Asterisk's media WebSocket and an AI provider's WebSocket are different protocols; an adapter must connect them.

Source-reviewed, 20 October 2026. This page maps Asterisk 22.8+ chan_websocket JSON control to OpenAI GPT-Live's server WebSocket as a candidate design. Phone Guides has not run this combination, published adapter code or tested a live call. The versions and message contract below are source-derived; interoperability remains unverified.

For the dated provider model/API and SDK versions, audio limits, lifecycle, pricing and data terms used across these examples, see the Asterisk AI provider contract checklist.

What owns each part

Part Responsibility
Asterisk Receives and routes the SIP call, supplies channel media, and keeps the caller channel in a bridge managed by an ARI application.
ARI application Decides when the AI path begins, creates and tracks the media channel, handles DTMF and call events, and moves the caller to a human or fallback route.
Media adapter Terminates the Asterisk media WebSocket, translates its binary audio and text control frames, manages a separate provider session, and releases both sides on hangup or error.
Voice API Receives the application's session start and audio events, returns audio and session events, and may delegate work to a backend.

Keep the API key and business-system credentials in the adapter's trusted server environment. Do not give a caller or an Asterisk media connection a provider secret. ARI control and media transport are separate connections; Asterisk warns against reusing one WebSocket for both ARI and media.

This route leaves call-control decisions with your ARI application. A provider-direct SIP design is different: the PBX may route the call away, and it may no longer see or control the AI media leg. Compare the choices in Asterisk AI integration architecture.

Pin the documented starting point

The current Asterisk WebSocket guide says chan_websocket begins in Asterisk 22.6.0. JSON control messages and the transport_data option for ARI ExternalMedia begin in 22.8.0. Use Asterisk 22.8.0 or later within the 22 branch for this JSON-based design, and check the installed branch's exact API and module documentation before building. The source does not prove that a FreePBX release exposes or supports this call path; follow FreePBX-owned customisation boundaries rather than editing generated files.

FreePBX 17 version and module checks

The official FreePBX 17 Debian installer defaults to Asterisk major version 22, but that setting does not identify the installed patch release or confirm which modules are present and loaded. Check the actual Asterisk version and chan_websocket.so state on the target system. A FreePBX issue report for Framework 17.0.19.25 with Asterisk 22.3.0 says the reporter could not find res_external_media.so; it is a report about that older build, not a current support statement. For this path, Asterisk documents chan_websocket as the channel driver selected by the ARI /channels/externalMedia endpoint with transport=websocket and encapsulation=none. Do not assume that res_external_media.so is the module name to install or load.

The FreePBX miscdests 17.0 branch registers destinations that route to a local number through its own dialplan context. Sangoma's BMO dialplan-hook documentation describes a hook that receives the generated extensions object during configuration application; its Extensions class guide describes adding entries to that generated dialplan. The FreePBX 17 Core module's versioned module definition declares a get_config callback.

There is also a process-management path for a custom FreePBX module. Sangoma's Process Management guide documents FreePBX::PM2() calls to start, stop, restart, inspect and remove module-owned background applications, and says the process need not be written in Node.js. The [FreePBX 17 pm2 module definition](https://github.com/FreePBX/pm2/blob/release/17.0/module.xml) identifies version 17.0.3.4 and support for FreePBX 17. Its versioned implementation contains those lifecycle methods. The FreePBX 17 Core module implementation is a first-party example: its install path starts a named process through PM2, and its uninstall path deletes it. This documents a module-owned process-supervision pattern; a dialplan hook alone does not start or supervise a persistent application.

These sources still do not define how an ARI session owns a caller and media channel, how the application bridges audio, or how each call and provider session is cleaned up. They do not certify an AI media path or establish that a packaged custom module will start, upgrade and uninstall correctly on a particular installation. Treat FreePBX AI-call compatibility as Unknown until the exact Framework, enabled module set, lifecycle hooks and Asterisk build are documented or pass a controlled integration test. A module appearing in module show proves availability and load state only.

OpenAI's current server WebSocket guide describes GPT-Live's primary connection at wss://api.openai.com/v1/live/sessions. The server sends session.start and receives session.started; the session selects a model, instructions, audio format, voice and delegation mode. The project API key stays on the application server. Do not substitute a legacy Realtime handshake or assume its event names and close behavior still apply.

The matching media setting to evaluate is:

Side Selected format Bytes on its media path
Asterisk chan_websocket ulaw Raw G.711 μ-law, 8 kHz. The Asterisk guide gives 160 bytes per 20 ms frame.
GPT-Live WebSocket {"type":"audio/pcmu","rate":8000} Raw G.711 μ-law, 8 kHz, base64-encoded inside JSON audio events.

These format names describe the same codec and sample rate. That may avoid a codec conversion in the adapter, but it does not prove the negotiated caller path or resulting audio quality. Verify the MEDIA_START format, both WebSocket directions and the caller leg. If the PBX channel negotiates another format, convert it explicitly or stop the trial; changing a format label does not convert bytes.

Define the adapter contract

The adapter handles two distinct protocols on separate sockets:

Asterisk media side Provider side Adapter action
Binary WebSocket frame with raw ulaw audio session.input_audio.append JSON event containing base64 raw audio Encode the ordered bytes as base64 and send an event. Do not wrap the audio in WAV or RTP headers.
session.output_audio.delta event with base64 audio Binary WebSocket frame with raw ulaw audio Decode the delta, retain order and send media to Asterisk in frame-size multiples or use the documented buffering commands.
JSON text control event such as MEDIA_START, DTMF_END, MEDIA_XOFF or MEDIA_XON GPT-Live session lifecycle and error events Translate only the required control meaning. Do not forward Asterisk control JSON as provider events.
JSON text command such as FLUSH_MEDIA or HANGUP Provider session update or close action Choose one call owner for each action and handle acknowledgments or errors. Asterisk and provider commands have distinct effects.

On connection, read MEDIA_START and confirm its codec and optimal_frame_size. Configure the provider session with the same audio/pcmu format before sending input. GPT-Live expects audio bytes encoded in each JSON event; chan_websocket carries raw audio in binary frames. The adapter performs this envelope conversion and preserves byte order. It must also handle connection setup, authentication, event correlation, provider errors and cleanup.

GPT-Live's WebSocket guide says audio appends have no acknowledgment. Keep application-side byte and playback counters rather than treating a successful socket write as proof the provider processed audio. The Asterisk channel reports MEDIA_XOFF and MEDIA_XON when its outbound-to-caller queue reaches flow-control thresholds; pause and resume the provider-audio sender in response. Bound your own queues too. Unbounded buffering can make a caller hear stale answers long after the conversation has moved on.

Call turns, keypad input and human fallback

GPT-Live continuously listens and speaks; its server WebSocket does not require the manual audio commit and response-start sequence used by older Realtime integrations. The application still owns audio playback. The primary WebSocket output has no audio timing fields and no event that marks the end of each spoken response, so track queued and played bytes in the adapter. Do not treat a transcript event as proof the caller heard the words.

If a caller starts speaking during generated audio, stop or flush stale output according to an application interruption policy. Asterisk's JSON media protocol supports FLUSH_MEDIA to discard queued, not-yet-played media. Coordinate that with the provider session and the ARI call state; flushing the Asterisk queue does not undo a backend action that already started. Test interruption at the start, middle and end of a long answer, including late tool results.

Handle DTMF as telephony input, not as recognized spoken text. The Asterisk media channel can report DTMF events received from the core. Route digits through explicit application logic, check what the calling carrier delivers, and do not assume the AI API will receive Asterisk's DTMF control event automatically.

Plan the human route before putting callers on the AI path. The ARI application should have an explicit transfer or fallback action for a request to speak to a person, an API failure, a media disconnect, timeout and caller hangup. Decide which application component moves the caller, what happens if the human destination is unavailable, and how late AI events are ignored after the caller has moved. OpenAI's direct-SIP transfer endpoint applies to its provider-direct call design; it is not an Asterisk bridge-transfer command.

Session and call lifecycle

  1. Receive the call in the intended Asterisk context and apply the same identity, time, access and destination checks used by the human route.
  2. Start the ARI application, establish the caller bridge and create a WebSocket external-media channel using the exact 22.8+ branch syntax. Use a dedicated per-call media connection and JSON control format.
  3. Confirm the external-media channel joined the intended bridge and that MEDIA_START reports ulaw and its frame size. Handle connection failure before opening the AI session.
  4. Start GPT-Live from the trusted adapter with the documented audio/pcmu 8 kHz format, chosen model and session settings. Wait for session.started; keep the caller on a clear fallback path if initialization fails.
  5. Bridge the two media streams through the adapter. Preserve caller audio while the agent speaks, handle flow control, track provider and Asterisk errors, and forward DTMF only through an explicit mapping.
  6. On transfer, stop sending or playing AI audio, end the AI session according to its close contract, remove the media channel and perform the human route through the ARI application. Ignore late events from the completed AI session.
  7. On caller hangup or provider loss, stop queues and remove the media channel and bridge resources. Close GPT-Live gracefully when the connection is still available; record final usage as unconfirmed if session.closed never arrives.

OpenAI documents session.closed as the event that provides final usage and close reason. Keep the provider connection open until it arrives when possible. A closed socket without that event is not evidence that final usage was confirmed. Track API session duration separately from any delegated backend usage.

Provider connection contracts are different

The OpenAI path above is one candidate, not a generic format for voice services. These official references describe different SIP and WebSocket contracts as checked on 20 October 2026:

Provider API Connection and audio contract Adapter consequence
OpenAI GPT-Live WebSocket is supported; OpenAI recommends WebRTC for audio. Audio is carried inside JSON events as base64 raw G.711 μ-law or A-law bytes at 8 kHz when that format is selected. With Asterisk ulaw, codec conversion may be avoidable, but the adapter still translates binary Asterisk frames to JSON/base64 and tracks ordered playback itself.
Deepgram Voice Agent Connect to its Voice Agent WebSocket, wait for Welcome, send a Settings message, and wait for SettingsApplied. The Plivo example selects raw μ-law at 8 kHz both ways; Voice Agent audio is carried in binary frames and its server events use Deepgram's own names. This format is a useful comparison for an Asterisk ulaw media path, not proof of an Asterisk connector. Translate Settings, function-call, cancellation, error and audio-done events explicitly. A cancellation notice does not establish whether an application-side action was reversed.
ElevenLabs ElevenAgents SIP trunk A managed agent can receive inbound SIP calls or send outbound calls through an imported trunk. SIP media uses PCMU/PCMA at 8 kHz or G.722 at 16 kHz; TLS 1.2+ is supported for signaling, and SRTP support depends on the trunk. SIP REFER human transfer requires trunk support and carries no warm transfer message. The trunk feature is limited to Enterprise accounts/trials. This is a provider-managed SIP call path, not an Asterisk media-WebSocket adapter. A SIP-compatible PBX can route a call to the service, but ElevenLabs does not document Asterisk/FreePBX support or the exact PBX transfer path. Verify the negotiated codec, TLS/SRTP, REFER behavior, call ownership, enterprise limits, pricing and retention settings with the selected account.
Microsoft Azure AI Voice Live Version 2026-07-15 is GA and uses server-to-server JSON events over WebSocket. The API accepts and emits G.711 μ-law/A-law at 8 kHz; session.created includes the server-set expires_at, while rate_limits.updated reports the resource's current quota. An Asterisk ulaw or alaw path may avoid codec resampling if the negotiated format matches, but the adapter must still translate JSON events and manage interruptions, quota and session expiry. The listed public rates are $- placeholders, and the Voice Live API does not establish an Asterisk or FreePBX connector.
Google Gemini Live API The Live API remains marked Preview and uses a stateful v1beta WebSocket contract; the selected gemini-3.8-live model is separately marked Stable. Client setup and realtime input use Gemini messages. Audio input is raw little-endian 16-bit PCM, natively 16 kHz; generated audio is raw PCM at 24 kHz. Google's session guide defines resumption tokens, GoAway.timeLeft, generationComplete and an interruption signal. An 8 kHz μ-law Asterisk stream needs decoding and resampling for input, with output conversion to the format and rate negotiated on the PBX media channel. Clear buffered output on provider interruption; handle resumption and GoAway as provider-session recovery, separately from Asterisk channel and bridge recovery. Carry its session and tool messages separately from OpenAI or Deepgram events.
Amazon Nova 2.5 Sonic Bedrock bidirectional streaming uses structured AWS event messages and SigV4, with AWS documentation showing 16-bit mono LPCM at 8, 16 or 24 kHz. The Nova 2 guide gives an eight-minute connection limit and a session-renewal pattern; the 2.5 service card says the API surface is the same but does not state its own duration cap. This is an adapter candidate, not an Asterisk or FreePBX connector. Decode G.711 to LPCM, translate Asterisk channel events to Bedrock events, and map provider barge-in back to Asterisk playback flush. Verify the Nova 2.5 duration and renewal behaviour for the chosen model/SDK before deployment. Provider launch regions are limited to four AWS regions listed in the dated contract checklist.

The provider documentation describes each provider's own API. It does not certify Asterisk or FreePBX support. Do not swap a model name into another provider's event contract or infer a working bridge from matching codec labels. Before selecting a second path, compare the exact model/API revision, turn and interruption behavior, final usage event, tool cancellation, rate limits, pricing, processing region and retention terms. See the AI call data and operations checklist for provider-specific data checks.

Optional framework: Strands Agents Bidi

AWS's current Strands Bidi quickstart demonstrates BidiAgent with Nova 2.5 Sonic model ID amazon.nova-2-5-sonic, tools and microphone/speaker I/O. The Python package strands-agents 1.61.1 was published on 15 October 2026; the voice quickstart requires Python 3.12 or later. Strands' custom I/O guide allows an input stream to read from a WebSocket and an output stream to send agent events back to an application.

This offers an agent-framework option for a custom Asterisk adapter. It does not remove the Asterisk protocol work: the application must map chan_websocket binary media and control events to Strands input/output streams, convert the negotiated G.711 audio to the provider's LPCM format, and coordinate barge-in, DTMF, transfer, hangup and failure handling. The Strands examples use local audio or browser WebSockets; they do not document chan_websocket, ARI or FreePBX integration. Do not assume BidiAgent.run() renews the Bedrock connection; AWS's eight-minute cap is documented in its Nova 2 guide, and the checked 2.5 service card does not state a duration. Verify renewal and cleanup with the exact package/model path before any live call. See the dated provider contract checklist for the framework and Bedrock limits, prices and data terms.

Test before a live route

Use a private test number and non-sensitive calls. Record the exact Asterisk patch, loaded modules, carrier and endpoint configuration, adapter revision, OpenAI model and connection guide checked date. Check each boundary independently:

  • DTMF or carrier audio arrives at the Asterisk core and the media adapter receives the expected MEDIA_START format.
  • Caller audio reaches the expected GPT-Live input event; generated provider audio returns to the Asterisk channel in order.
  • Two-way speech, silence, overlap, barge-in and long answers work without stale playback or unbounded queues.
  • MEDIA_XOFF pauses output and MEDIA_XON resumes it; connection and provider errors stop audio safely.
  • DTMF, human transfer, unavailable destination, caller hangup and adapter restart each follow the planned route.
  • A provider timeout before session start differs from loss during a running call; close and usage status are recorded accurately.
  • Representative conversations are checked for task completion, spoken numbers and names, interruptions, incorrect actions, transfer behavior and final cost. One successful call is not a performance result.

Do not label this candidate path as FreePBX-compatible until a FreePBX release and supported extension point are identified. Do not label it tested until the exact PBX, carrier, adapter and provider versions have passed the call matrix.

Sources and limits

No cited source supplies a ready Asterisk-to-GPT-Live connector. The event and format mapping above is a candidate adapter contract assembled from separate product documentation. The complete call path, carrier interoperability, generated-audio behavior, turn interruptions and human transfer remain untested by Phone Guides.