Genesys AudioHook ist 8 kHz µ-law, und es gibt keine Stelle, an der man stehen könnte

Jede Spezifikationsaussage unten ist aus Genesys' eigener veröffentlichter Dokumentation zitiert und verlinkt; die Zitate geben wir im englischen Original wieder, weil es auf den exakten Wortlaut ankommt. Wo wir etwas nicht bestätigen konnten, steht es als unbestätigt gelistet statt aufgefüllt — dafür gibt es einen Abschnitt gegen Ende. Sollte etwas davon falsch sein oder sich ändern, sagen Sie es uns, und wir korrigieren es mit Datum.

Contact Center sind der Ort, an dem Voice AI auf tatsächlichen Umsatz trifft, und Genesys Cloud ist eines der größten davon. Die Frage, die für jeden zählt, der Audioverarbeitung verkauft, ist also eng und beantwortbar: Wie sieht der Medienpfad aus, und gibt es darin eine Stelle, an der ein Dritter stehen kann?

Die Genesys-Antwort ist ungewöhnlich gut lesbar, weil sie das Protokoll veröffentlichen, statt es zu beschreiben. Hier ist die gesamte Abtastratenfrage, so wie sie in ihren Typdefinitionen steht:

type MediaFormat = 'PCMU';
type MediaRate = 8000;

Kein Default. Keine Empfehlung. Ein Literal-Typ. Die Protokollreferenz wiederholt es in Prosa — "Sample rate of the media format in Hertz. The Genesys Cloud client currently only supports 8000Hz" — und der String 16000 kommt nirgendwo in der AudioHook-Spezifikation vor.

Das ist der Keil, um den es auf dieser ganzen Website geht, formuliert von der Plattform selbst. Jeder Dritte, der Audio über das dokumentierte Protokoll in Genesys Cloud integriert, erhält schmalbandiges G.711 µ-law, und im Wesentlichen jedes Modell zur Sprachverbesserung (speech enhancement) am Markt ist breitbandig trainiert.

Der Transport, in Kürze

AudioHook kehrt die Rollen um, die man erwarten würde. Genesys ist der WebSocket-Client; Ihr Service ist der Server.

"The AudioHook protocol uses WebSockets over TLS as the transport and is designed to make it easy to implement servers that accept it." — Einführung

Konkret, aus der Security-Seite und dem Session-Walkthrough:

Eigenschaft	Wert
Port	443, und nur 443
TLS	1.2 und 1.3; Zertifikate müssen von einer öffentlichen CA signiert sein (keine selbstsignierten)
Framing	JSON in Text-Frames, rohes Audio in Binary-Frames
Maximale Nachrichtengröße	64,000 Bytes, für Text wie Binary
Timeouts für Open / Ping / Close	5,000 ms / 5,000 ms / 10,000 ms
Application-Ping-Intervall	alle 5 Sekunden pro Verbindung
Auth	X-API-KEY-Header, plus optionales HMAC-SHA256-Request-Signing mit verpflichtender Nonce
Retries	bis zu 5, exponentielles Backoff

Zwei Details lohnt es herauszuziehen, weil sie Implementierer beißen.

Der Ping ist nicht der WebSocket-Ping. Das sind ping/pong-JSON-Nachrichten auf Anwendungsebene — "a protocol feature distinct from the WebSocket ping/pong messages (which are not used)" —, und ein unaufgefordertes pong ist ein Protokollfehler. Sie haben fünf Sekunden zum Antworten, alle fünf Sekunden, sonst behandelt Genesys die Verbindung womöglich als verloren und baut sie neu auf.

Es gibt kein WebSocket-Subprotokoll. Wir haben gezielt danach gesucht. Der dokumentierte Handshake trägt die Header Audiohook-Organization-Id, Audiohook-Correlation-Id, Audiohook-Session-Id und X-API-KEY, und überhaupt kein Sec-WebSocket-Protocol; der String taucht auf keiner Seite der AudioHook-Spezifikation auf. Wer vorhatte, über das Subprotokoll zu routen, routet stattdessen über den Pfad.

Die Medienverhandlung, und was die zwei Kanäle wirklich sind

Die open-Nachricht trägt ein Angebot, und Ihre opened-Antwort wählt daraus aus, SDP-artig. Die Regel ist strikt:

"The server must choose exactly one of the entries offered and must not modify an offered media format (including the channels and their order). This is similar to the offer-answer exchange of an SIP/SDP media negotiation, just simpler." — Session-Walkthrough

Ein typisches Angebot sind drei Einträge, alle PCMU mit 8000 Hz, die sich nur in den Kanälen unterscheiden: ["external", "internal"], ["external"], ["internal"].

Die Kanalnamen sind der Teil, den die Leute falsch verstehen, und sie heißen nicht „Anrufer" und „Agent". AudioHook folgt einem Teilnehmer, nicht einem Leitungsabschnitt:

"Currently, two values are supported: external, which represents what the party represented by they participant speaks and internal, which represents what they hear." — Protokollreferenz

internal ist also alles, was dieser Teilnehmer hört — das können IVR-Ansagen sein, ACD-Wartemusik oder, in einer Konferenz, ein Mix. Genesys sagt das ausdrücklich: "the audio of the 'internal' channel in our AudioHook represents a mix of the audio from both agents." Wenn Sie irgendetwas bauen, das eine Stimme pro Kanal annimmt, scheitert diese Annahme bei einem Warm Transfer. In einer Stereo-Antwort ist links Index 0 und rechts Index 1.

Framegrößen: Es gibt keine

Das ist die wahrscheinlichste Quelle eines Bugs in einer ersten Implementierung, und die Spezifikation ist unverblümt dazu.

"The number of samples per frame is variable and is up to the client... The server must not make any assumptions about audio frame sizes and maintain a timeline of the audio stream by counting the samples." — Session-Walkthrough

Die einzige konkrete Zahl ist illustrativ: Ein 100-ms-Frame zweikanaligen PCMU mit 8000 Hz hat 1600 Bytes, ohne Header und interleaved. Ihr Framing-Budget sind die Nachrichtenobergrenze von 64,000 Bytes und die Rate-Limits — 10 Binärnachrichten pro Sekunde im Durchschnitt mit einem Burst von 25, dasselbe für Text.

Und der Stream ist nicht wie ein Telefonanruf getaktet. Genesys puffert:

"The client maintains a history buffer of at least 20 Seconds of audio... it will send the buffered audio to the server faster than real-time and then continue with the real-time stream. The rate at which the client 'catches up' is undefined."

Eine Session beginnt also mit einem Burst an Historie mit unspezifizierter Rate und pendelt sich dann auf Echtzeit ein. Alles, was Sie mit fester Blockgröße bauen — und das ist jedes Streaming-Modell zur Sprachverbesserung, unseres eingeschlossen —, braucht davor einen eigenen Re-Framing-Puffer, und alles, was den Echtzeitfaktor aus der Wanduhr-Ankunftszeit misst, liest in den ersten Sekunden Unsinn.

Wenn der Client nicht hinterherkommt, sagt er es Ihnen, mit einer discarded-Nachricht, die die Dauern start und discarded trägt, samt der Invariante position = start + discarded. Das ist eine Lückenansage, kein Steuerkommando: "whenever there is a discontinuity in the audio stream due to unexpected loss of audio." Explizites Pausieren und Fortsetzen produziert keine. Wenn Sie Samples zählen, um eine Zeitleiste zu führen — und die Spezifikation trägt Ihnen das auf —, dann ist discarded die Art, wie Sie erfahren, dass sich Ihre Zeitleiste gerade verschoben hat.

Die Frage, die alles entscheidet: Können Sie Audio zurücksenden?

Das hängt vollständig davon ab, welches der vier AudioHook-Features Sie implementieren, und die Antworten ähneln einander nicht.

Feature	Audio zu Ihrem Server	Audio zurück in den Anruf	Was Sie zurückgeben dürfen
AudioHook Monitor	Ja, external und/oder internal	Nein	Nichts in-band
Audio Connector	Ja, nur external	Ja — wird dem Anrufer vorgespielt	Audio, als Bot-Prompts
Transcription Connector	Ja	Nein	transcript-Events
Bot Transcription Connector	Ja (PCMU oder L16)	Nein	transcript- und Sprach-Events

AudioHook Monitor ist ein Abgriff und sagt das auch. Die Features-Seite lässt keinen Raum für Interpretation:

"here the client will stream the conversation audio to the server but no in band data can be sent back to the client. Data returned by the server will be silently ignored and discarded."

Beachten Sie das silently. Kein Fehler, keine Warnung — Ihr verarbeitetes Audio verschwindet, und die Session sieht gesund aus. Die Einführung rahmt das ganze Protokoll genauso: "Think of this as 'taps' on the audio streams to and from participants' parties."

Audio Connector ist tatsächlich bidirektional, und das ist der Kandidat, der auf den ersten Blick wie die Öffnung aussieht:

"This feature supports bi-directional audio streaming... Any audio data sent to the client will be played to the caller. Only the external audio channel is sent from the client to the server." — Features

Er hat die Maschinerie, die man dafür erwarten würde: die Client-Nachrichten playback-started und playback-completed, ein barge_in-Server-Event, eine dtmf-Nachricht. Server-zu-Client-Audio ist gedeckelt auf "no more than 64,000 bytes per message" und getaktet — "the server should not send audio more often than every 200ms".

Es gibt einen dokumentierten Widerspruch, den man kennen sollte, bevor man einen Tag darauf verwendet. Die Fehlertabelle in derselben Protokollreferenz sagt nach wie vor das Gegenteil:

"415 Unsupported Media Type — The server sent a binary message to the client... sending audio from the server to the client is not supported."

Unsere Lesart ist, dass 415 älter ist als Audio Connector und für Monitor- und Transcription-Connector-Sessions gilt, wo Binärdaten vom Server tatsächlich illegal sind; der Changelog zeigt bidirektionales Audio, DTMF, Playback und Barge-in als spätere Ergänzung. Aber die Spezifikation enthält heute beide Aussagen, und wer dagegen baut, sollte damit rechnen, empirisch herauszufinden, welche für seinen Session-Typ gilt.

Warum Audio Connector trotzdem kein Einfügepunkt ist

Hier schließt die Architektur die Tür, nicht das Protokoll. Audio Connector ist ein Bot-Turn, kein Inline-Filter, und drei seiner Eigenschaften sind je für sich disqualifizierend für jeden, der Audio säubern will, bevor der Bot eines anderen es hört:

"The Call Audio Connector action in Architect forks the voice stream, sends it to the configured URL, and then pauses the flow execution at this point, until the bi-directional stream ends... The bi-directional streaming session is active only in the IVR channel. It does not transfer to an agent." — Audio-Connector-Übersicht

1. Das Audio, das Sie senden, geht an den Anrufer, nicht an den Bot. Man bittet Sie, die Stimme am anderen Ende zu sein. Eine Richtung „gib das gesäuberte Anrufer-Audio zurück, und der Recognizer der Plattform hört stattdessen dieses" existiert nicht, denn die Richtung, die existiert, zeigt auf den Menschen.
2. Es ist eine Verzweigung mit blockierendem Flow. Die Ausführung stoppt an der Action und läuft weiter, wenn Ihre Session endet. Das ist ein Dialog-Turn, keine Pipeline-Stufe.
3. Es erreicht nie einen Agenten. Nur IVR.

Dazu die kleineren Beschränkungen, alle auf derselben Seite dokumentiert: ein bidirektionaler Stream, nur der external-Kanal, 300 gleichzeitige Audio-Connector-Anrufe und eine Obergrenze von 900 Sekunden pro Anruf, und keine Unterstützung unter BYOC Premises.

Die ehrliche Schlussfolgerung, Oberfläche für Oberfläche geprüft, lautet also: Genesys Cloud dokumentiert Audio-Egress, Audio-Dialog im IVR-Abschnitt und Metadaten-Rückgabe. Es dokumentiert keinen Weg, auf dem ein Dritter Audio empfängt, es verarbeitet und das verarbeitete Audio zu dem wird, was die eigenen nachgelagerten Konsumenten der Plattform hören. Wir haben geprüft: Monitor, Audio Connector, Transcription Connector, Bot Transcription Connector, Genesys Agent Assist (ein Wissensanzeige-Feature ganz ohne Audiopfad), Genesys Bot Connector (Text und Intents, nur Message-Flows) und Bring Your Own Interactions (nachträgliche Ingestion, keine Live-Medien).

Wo Sie stehen können, und es ist genau eine Stelle

Es gibt einen echten Einfügepunkt, und es ist nicht der, nach dem die Leute suchen.

Wenn Sie der Speech Recognizer sind, können Sie das Audio vor Ihrem eigenen Recognizer säubern. Der Bot Transcription Connector existiert genau dafür, einen Dritten die STT-Engine sein zu lassen — "allows audio to be streamed to the AudioHook-based server that will serve as an STT engine" —, und Genesys' eigenes Help Centre beschreibt ihn als den Weg, "integrate third-party ASR engines using the Genesys AudioHook protocol". Dieser Pfad empfängt PCMU, bietet als einziger auch L16 an und gibt transcript- und Speech-Start-Events zurück statt Audio.

Was die Frage verlagert, statt sie zu beantworten. Innerhalb dieser Grenze gehört Ihnen die ganze Kette: 8 kHz µ-law rein, Ihre Verarbeitung, Ihr Recognizer, Transkript raus. Nichts in der Plattform hindert Sie daran, dort ein Filter einzusetzen. Was Sie hindert, ist, dass nach unseren eigenen Messungen das meiste, was man dort einsetzen könnte, derzeit eine schlechte Idee ist: Über unsere sieben Telefonie-Bedingungen produzierte keine getestete Engine eine nennenswerte Verbesserung gegenüber dem unverarbeiteten Audio, und mehrere verschlechterten es um fünf bis zehn Punkte Wortfehlerrate (WER). Die Stelle zum Stehen existiert. Gefehlt hat etwas, mit dem es sich lohnt, dort zu stehen — und das ist der gesamte Grund, warum es diese Firma gibt.

Die Konsequenz zweiter Ordnung ist es wert, für jeden ausgesprochen zu werden, der Plattformauswahl betreibt. Auf AudioHook wird die Audioqualitätsentscheidung für Ihren umsatzstärksten Kanal stromaufwärts von Ihnen getroffen und kann von Ihnen nicht geändert werden. Sie bekommen 8 kHz µ-law und was auch immer die Carrier-Strecke damit gemacht hat, und der einzige Hebel, den Sie haben, ist, was Sie tun, nachdem es angekommen ist.

Was wir nicht bestätigen konnten

Ausdrücklich benannt, denn ein Beitrag für Entwickler, der Lücken stillschweigend auffüllt, ist nichts wert.

• Die Abtastrate von Genesys' eigener Transkription. Wir konnten keine Genesys-Aussage dazu finden, mit welcher Rate deren eigenes Speech-to-Text läuft, und nirgends einen Vergleich von 8 kHz gegen 16 kHz. Ihre Engines sind herstellergestützt (Google, Microsoft Azure, AWS Transcribe, eine native Genesys-Engine, Deepgram), und für keine davon ist eine Rate veröffentlicht. Trunk-Codecs können G.722 und Opus einschließen, die Carrier-Strecke ist also nicht notwendigerweise Schmalband — aber was den Transcriber erreicht, ist undokumentiert. Die Zahl 8000 Hz in diesem Beitrag betrifft ausschließlich den AudioHook-Drittanbieterpfad. Übertragen Sie sie nicht auf unser Wort hin auf Genesys' eigene Pipeline.
• Irgendein unterstützter Weg, einen SBC oder Medienserver in einen BYOC-SIP-Pfad einzufügen, um Audio zu verändern. BYOC Cloud erlaubt, SIP-Trunks zu Drittanbieter-Carriern zu definieren, und Trunk-Codecs sind konfigurierbar. Wir fanden kein Genesys-Dokument, das ein Verarbeitungselement in diesem Pfad billigt, beschreibt oder verbietet. Fehlende Dokumentation ist weder Erlaubnis noch Verbot.
• Eine Höchstzahl gleichzeitiger AudioHook-Monitor-Verbindungen. Veröffentlicht sind nur Integrations- und Monitor-Zahlen — fünf AudioHook-Monitor-Integrationen, bis zu 20 Integrationsinstallationen, bis zu 500 konfigurierte Monitore, zehn Transcription-Connector-Integrationen. Audio Connectors 300 gleichzeitige Anrufe sind die einzige Nebenläufigkeitszahl, die wir fanden.
• Das Drahtformat von Server-zu-Client-Audio im Audio Connector. Die Spezifikation nennt den Takt (nicht öfter als alle 200 ms) und die Größenobergrenze (64,000 Bytes), wiederholt aber nie das Format. Es ist vermutlich das verhandelte. Sie sagt es nicht.
• „AudioHook Media Service" scheint kein Genesys-Produktname zu sein. Wir haben die Sitemap des Developer Centre und den vollständigen Artikelindex des Help Centre durchsucht und nichts gefunden. Wenn Sie den Begriff gesehen haben: Aus der Genesys-Dokumentation stammt er nicht.

Wir vermerken außerdem, dass Genesys eine Referenz-Serverimplementierung in TypeScript mit Client-Tool und Testsuite veröffentlicht, sowie einen separaten Audio-Connector-Referenzserver, dessen Quelltext MediaFormat auf 'PCMU' | 'L16', MediaRate auf 8000 und die maximale Binärnachricht auf 64000 festnagelt — eine zweite, unabhängige Bestätigung der Zahlen oben, in Code statt Prosa.

Wenn Sie das implementieren

1. Zählen Sie Samples, nicht Frames. Die Spezifikation verlangt es, und der Aufhol-Burst bestraft alles, was es nicht tut.
2. Puffern Sie in die Blockgröße Ihres Modells, und nehmen Sie in den ersten zwanzig Sekunden das Ankunfts-Timing nie als Stellvertreter für das Audio-Timing.
3. Behandeln Sie discarded als Zeitleisten-Ereignis, nicht als Fehler, den man loggt und hinter sich lässt. Ihr Sample-Zähler ist danach falsch, wenn Sie es nicht tun.
4. Antworten Sie auf ping innerhalb von fünf Sekunden, immer, aus einem Pfad, den Inferenz nicht blockieren kann. Teilen sich Ihr Modell und Ihre Control Plane eine Event-Loop, frisst ein langsamer Block Ihre Verbindung.
5. Entscheiden Sie, welches Feature Sie sind, bevor Sie irgendetwas entwerfen. Monitor und Audio Connector sehen aus wie dasselbe Protokoll und sind entgegengesetzte Architekturen, und die Fehlertabelle wird Sie nicht davon abhalten, das falsche zu bauen.
6. Beachten Sie die PCI-Grenze. AudioHook hält PCI-DSS-Konformität ein, wenn Secure Pause während Secure Flows läuft, und Sie können damit während eines Secure Flow kein Audio streamen. Was immer Sie bauen, hat per Design ein Loch, und dieses Loch ist Absicht.

Der Begleitbeitrag zu Amazon Connect, Twilio, NICE CXone und Avaya liest dieselbe Frage gegen die anderen vier Plattformen — und eine davon dokumentiert, wie sich zeigt, etwas, das Genesys nicht dokumentiert.