Skip to content
Phone Guides

Asterisk external media and speech integrations

A speech service needs an audio path as well as an application control path. Start by describing who receives audio, who produces it, and which component decides when the caller can interrupt. An HTTP request that creates a resource does not carry the caller's audio by itself.

Source-reviewed, 20 October 2026. Prepared from the cited documentation. No external media or speech service has been independently tested by Phone Guides. Scope: interface selection and deployment design; service compatibility remains specific to the installed versions and documented transport.

For dated provider SDK/API versions, audio limits, session lifecycle, pricing and data terms, see the Asterisk AI provider contract checklist.

Separate call control from audio processing

Use the official ARI media introduction to identify the channels, bridges and media resources involved in an ARI application. Use the exact branch API for the resource you intend to create. Do not infer an arbitrary external service's accepted transport from its ability to accept ordinary web requests.

The AEAP protocol reference describes setup, parameter exchange and error responses. That protocol description is one part of the integration: the Asterisk module and external implementation must agree on the actual media and service behaviour.

Trace the official speech-to-text demonstration

Asterisk's external speech-to-text example is a useful concrete path to review: Asterisk sends audio to a local application using AEAP, and that application uses a separate provider connection. It is an upstream demonstration, not a Phone Guides compatibility or production-readiness result.

Its backend uses Node.js and Google Speech credentials. Review its actual dependency versions, current provider requirements, costs and data handling before deploying it. Linking this example does not install those dependencies in Phone Guides or establish that every current SDK combination works.

Check the example's current dependency and API boundary

The upstream repository's [package.json](https://github.com/asterisk/aeap-speech-to-text/blob/master/package.json) allows @google-cloud/speech ^4.9.0, ws ^8.3.0 and yargs ^17.3.1; its lockfile records @google-cloud/speech 4.10.0. These are the repository's recorded values, not a recommendation to install them today. Its visible README describes Asterisk 18.12.0+/19.4.0+ and its repository has no published release entries, so record the exact source revision and runtime before evaluating a deployment.

The example calls SpeechClient().streamingRecognize() with a Speech-to-Text v1-style config object. Google's current streaming guide, last updated 13 October 2026, demonstrates v2 with a recognizer resource and streaming request messages; that guide sets a 25 KB limit for the initial request and each message. Google's current v1 protocol definition still defines StreamingRecognize as a gRPC method, with a distinct request shape. Keep the v1 and v2 limits and request formats tied to their cited API version; the v2 guide does not by itself establish a limit or migration path for this v1 example. The dated provider contract checklist records the matching package lock, the current v2 price and the API distinction.

There is also a runtime and client-library upgrade boundary. Google's Node client changelog lists release 8.2.0 on 8 October 2026 and says major version 8 requires Node.js 22. The upstream AEAP example's ^4.9.0 range and 4.10.0 lockfile do not select that newer major. A major-version or API-version change needs its own review of constructor and request shapes, Node runtime, stream setup, chunk sizing, result events, cancellation and billing. A dependency version change alone does not establish that the sample was ported or tested.

The source review also found two points to investigate before trusting provider settings: the sample provider lists only en-US and maps ulaw, slin16 and opus; in its codec configuration path it writes encodingencoding while the default request object uses encoding. That source-level discrepancy may prevent a negotiated codec override from reaching the Google request. This has not been executed here, so it is recorded as an unresolved code-review finding rather than a confirmed runtime result. The sample also writes transcripts to debug output; redirect or remove transcript logging before using private caller audio.

Google's current guide requires an enabled API and billing for the demonstrated cloud workflow and uses Application Default Credentials. Keep credentials on the server side with least-privilege access. Confirm the provider's current pricing, retention terms, supported language/model, audio format, per-stream limits and cancellation behaviour for the chosen project and API version; none of those service terms is established by the Asterisk AEAP protocol.

For a deliberately local application listening on port 9099, an original named client fragment in the configuration owning aeap.conf is:


[pg-stt-local]
type=client
codecs=!all,ulaw
url=ws://127.0.0.1:9099
protocol=speech_to_text

The Asterisk 22.11.0 AEAP sample defines these fields. This loopback URL describes only the Asterisk-to-local-application leg. In separate containers or hosts, loopback is a different destination; do not expose the demonstration listener publicly to compensate. Establish the documented protected/authenticated arrangement for a remote service instead.

Inspect the installed components before attempting a call:


module show like aeap
module show like speech
core show application SpeechCreate

The application lifecycle then has distinct stages:

  1. Select this client name as the engine for SpeechCreate(). The branch-22 reference documents the ERROR variable when the engine cannot be used. Define the caller's fallback before continuing.
  2. Start recognition and invoke the intended prompt/input operation. Confirm the prompt is installed and the backend's accepted audio format and language match the task.
  3. Interpret the recognition result under the application's own input/authorisation rules. A transcript is external data, not a dialplan command or proof of caller identity.
  4. Destroy the speech resource and release related work on normal completion and hangup. Preserve late-result handling so an ended interaction cannot affect a different call.

The SpeechBackground reference documents its timeout and failure behaviour. Its timeout starts after playback stops, so it is not an overall time limit for the entire external service transaction. If its documented failure hangup is unsuitable, use the documented wrapper/fallback arrangement rather than assuming later priorities always run.

The upstream demonstration prints recognised text. Do not copy that logging behaviour into a private-data workflow by default. Keep transcripts and provider credentials out of ordinary PBX logs, and account for the provider leg separately from the local AEAP connection. This source-backed walkthrough remains unexecuted by Phone Guides.

Define the service contract

Decision Record before connecting callers
Direction Caller audio sent, generated audio returned, or both
Format Codec, sample format/rate and any conversion performed
Timing Connection limit, maximum response wait and cancellation
Recognition Language, grammar or model selection and result format
Playback Start, completion, interruption and queued-audio handling
Failure A defined prompt, human route or other safe caller treatment
Data Audio/transcript destination, retention, access and redaction

Keep a missing result distinct from a negative business result. A timeout while checking an account cannot establish that the account does not exist. If a service can return partial results, decide which results permit a routing decision and which only update a display.

Handle interruption and cleanup

Define what happens when the caller presses a digit, speaks over playback, hangs up, or transfers while work is pending. Cancel work where supported and discard late results that no longer belong to the active interaction. Do not let an old response start playback on a reused application record.

For resource ownership and repeated cleanup, follow ARI call lifecycle handling. For transaction and fallback decisions, use IVR service integration. Keep call identifiers distinct from customer identifiers in logs.

Protect and observe the path

Document where audio leaves the PBX and the trust arrangement for every connection. PBX-to-phone encryption does not establish protection on a separate service connection. Keep service credentials server-side and restrict destinations and permitted operations.

Observe connection failures, response time, abandoned work and format errors without logging full audio or transcripts by default. A service health check should be distinguishable from a successful speech interaction.

Reader checks

On your own exact service path, check supported audio formats, expected language, silence, interruption, a slow response, an unavailable service and hangup during processing. Inspect active resources afterwards. Record what was actually exercised; a successful prerecorded audio request does not establish live conversational behaviour.

Return to Asterisk documentation.