Genesys AudioHook Serializer

​

Overview

​

Installation

uv add "pipecat-ai"

​

Prerequisites

​

Genesys Cloud Setup

1. Genesys Cloud Organization: Access to a Genesys Cloud org with AudioHook enabled
2. AudioHook Integration: Configure an AudioHook integration in Genesys Cloud admin
3. Architect Flow: Create an Architect flow that uses the AudioHook action to connect calls to your Pipecat application
4. WebSocket Endpoint: A publicly accessible WebSocket endpoint for Genesys to connect to

​

Key Features

• Bidirectional Audio: Stream audio between Genesys and Pipecat in PCMU format at 8kHz
• Protocol Handshake: Automatic handling of open/opened, close/closed, and ping/pong messages
• DTMF Handling: Process touch-tone events from callers
• Barge-in Support: Notify Genesys when the user interrupts bot audio
• Pause/Resume: Handle hold scenarios, and pause or resume the stream from your bot
• Architect Variables: Pass input/output variables between Architect flows and your bot
• Stereo Support: Process external (customer) audio, internal (agent) audio, or both channels

​

Configuration

​

InputParams

​

Usage

​

Basic Setup

from pipecat.serializers.genesys import GenesysAudioHookSerializer
from pipecat.transports.websocket.fastapi import (
    FastAPIWebsocketTransport,
    FastAPIWebsocketParams,
)

serializer = GenesysAudioHookSerializer()

transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        serializer=serializer,
        audio_out_10ms_chunks=20,
    ),
)

​

With Language Support

serializer = GenesysAudioHookSerializer(
    params=GenesysAudioHookSerializer.InputParams(
        supported_languages=["en-US", "es-ES", "fr-FR"],
        selected_language="en-US",
    )
)

​

Accessing Call Metadata

# Participant info (ani, dnis, etc.)
participant = serializer.participant

# Custom input variables from the Architect flow
input_vars = serializer.input_variables

# Conversation and session IDs
conversation_id = serializer.conversation_id
session_id = serializer.session_id

​

Setting Output Variables

# Set variables during the conversation
serializer.set_output_variables({
    "intent": "billing_inquiry",
    "customer_verified": True,
    "summary": "Customer asked about their bill",
    "transfer_to": "billing_queue",
})

​

Server-Initiated Disconnect

from pipecat.frames.frames import OutputTransportMessageUrgentFrame

# Send a disconnect message through the pipeline
disconnect_msg = serializer.create_disconnect_message(
    reason="completed",
    action="transfer",
    output_variables={"intent": "resolved"},
)
await worker.queue_frame(OutputTransportMessageUrgentFrame(message=disconnect_msg))

​

Event Handlers

@serializer.event_handler("on_open")
async def on_open(serializer, message):
    logger.info(f"Session opened: {serializer.conversation_id}")

@serializer.event_handler("on_close")
async def on_close(serializer, message):
    logger.info("Session closing")

@serializer.event_handler("on_dtmf")
async def on_dtmf(serializer, message):
    digit = message.get("parameters", {}).get("digit")
    logger.info(f"DTMF digit pressed: {digit}")

@serializer.event_handler("on_paused")
async def on_paused(serializer, message):
    logger.info("Audio paused (caller on hold)")

@serializer.event_handler("on_resumed")
async def on_resumed(serializer, message):
    logger.info("Audio resumed")

​

Frames

​

Methods

​

create_pause_request()

def create_pause_request() -> dict[str, Any]

await worker.queue_frame(
    OutputTransportMessageUrgentFrame(message=serializer.create_pause_request())
)

​

create_resume_request()

def create_resume_request() -> dict[str, Any]

await worker.queue_frame(
    OutputTransportMessageUrgentFrame(message=serializer.create_resume_request())
)

​

create_resumed_response()

def create_resumed_response() -> dict[str, Any]

​

Protocol Details

​

AudioHook v2 Protocol

• Text frames: JSON control messages for session lifecycle (open, close, ping, pause, resume, etc.)
• Binary frames: Raw audio data in PCMU or L16 format

​

Message Flow

1. Genesys connects to your WebSocket endpoint
2. Genesys sends an open message with session metadata
3. The serializer automatically responds with opened
4. Bidirectional audio streaming begins via binary frames
5. Genesys sends periodic ping messages; the serializer responds with pong
6. When the call ends, Genesys sends close; the serializer responds with closed (including any output variables)

​

Audio Format

• Default encoding: PCMU (mu-law) at 8kHz mono
• Automatic resampling: The serializer converts between the 8kHz Genesys format and your pipeline’s sample rate using Pipecat’s built-in resampling
• Stereo handling: When channel is set to "both", Genesys sends stereo audio with external (customer) on the left channel and internal (agent) on the right. The serializer extracts the external channel for processing.

​

Notes

• Fixed packet size: Set audio_out_10ms_chunks=20 on your transport parameters. This sends outbound audio in 200 ms packets, since Genesys rate-limits incoming messages.
• No extra dependencies: The serializer uses Pipecat’s built-in G.711 conversion functions (pcm_to_ulaw, ulaw_to_pcm in pipecat.audio.g711) and audio resampler.
• Pause/resume: When Genesys pauses the stream (e.g., caller placed on hold) it sends paused, and the serializer drops incoming and outgoing audio until Genesys sends resumed. Use create_pause_request() and create_resume_request() to ask Genesys to pause or resume.
• Output variables: Variables set via set_output_variables() are included in the closed response when Genesys terminates the session. These variables become available in the Architect flow for routing decisions.
• L16 format: The serializer accepts AudioHookMediaFormat.L16 as a configuration option but drops all audio in both directions with it. Use PCMU (the default).