genesys

Genesys AudioHook Serializer for Pipecat.

This module provides a serializer for integrating Pipecat pipelines with Genesys Cloud Contact Center via the AudioHook protocol.

Features: - Bidirectional audio streaming (PCMU μ-law at 8kHz) - Automatic protocol handshake handling (open/opened, close/closed, ping/pong) - Input/output variables for Architect flow integration - DTMF event support - Barge-in (interruption) events - Pause/resume support for hold scenarios (optional)

Protocol Reference: - https://developer.genesys.cloud/devapps/audiohook

Audio Format: - PCMU (μ-law) at 8kHz sample rate (preferred) - L16 (16-bit linear PCM) at 8kHz also supported - Mono (external channel) or Stereo (external on left, internal on right)

class pipecat.serializers.genesys.AudioHookMessageType(*values)

Bases: StrEnum

AudioHook protocol message types.

OPEN = 'open'

OPENED = 'opened'

CLOSE = 'close'

CLOSED = 'closed'

PAUSE = 'pause'

RESUMED = 'resumed'

PING = 'ping'

PONG = 'pong'

UPDATE = 'update'

EVENT = 'event'

ERROR = 'error'

DISCONNECT = 'disconnect'

class pipecat.serializers.genesys.AudioHookChannel(*values)

Bases: StrEnum

AudioHook audio channel configuration.

EXTERNAL = 'external'

INTERNAL = 'internal'

BOTH = 'both'

class pipecat.serializers.genesys.AudioHookMediaFormat(*values)

Bases: StrEnum

Supported audio formats.

PCMU = 'PCMU'

L16 = 'L16'

class pipecat.serializers.genesys.GenesysAudioHookSerializer(params: InputParams | None = None, **kwargs)

Bases: FrameSerializer

Serializer for Genesys AudioHook WebSocket protocol.

This serializer handles converting between Pipecat frames and Genesys AudioHook protocol messages. It supports:

• Bidirectional audio streaming (PCMU at 8kHz)

• Automatic protocol handshake (open/opened, close/closed, ping/pong)

• Session lifecycle management with pause/resume support

• Custom input/output variables for Architect flow integration

• DTMF event handling

• Barge-in events for interruption support

The AudioHook protocol uses: - Text WebSocket frames for JSON control messages - Binary WebSocket frames for audio data

Example usage:

serializer = GenesysAudioHookSerializer(
    params=GenesysAudioHookSerializer.InputParams(
        channel=AudioHookChannel.EXTERNAL,
        supported_languages=["en-US", "es-ES"],
        selected_language="en-US",
    )
)

# Use with FastAPI WebSocket transport
transport = FastAPIWebsocketTransport(
    websocket=websocket,
    params=FastAPIWebsocketParams(
        audio_in_enabled=True,
        audio_out_enabled=True,
        serializer=serializer,
        audio_out_fixed_packet_size=1600,  # Important: prevents 429 rate limiting from Genesys
    ),
)

# Access call information after connection
participant = serializer.participant  # ani, dnis, etc.
input_vars = serializer.input_variables  # Custom vars from Architect

# Set output variables to return to Architect
serializer.set_output_variables({"intent": "billing", "resolved": True})

Parameters:

PROTOCOL_VERSION – The AudioHook protocol version (currently “2”).

PROTOCOL_VERSION = '2'

class InputParams(*, ignore_rtvi_messages: bool = True, genesys_sample_rate: int = 8000, sample_rate: int | None = None, channel: AudioHookChannel = AudioHookChannel.EXTERNAL, media_format: AudioHookMediaFormat = AudioHookMediaFormat.PCMU, process_external: bool = True, process_internal: bool = False, supported_languages: list[str] | None = None, selected_language: str | None = None, start_paused: bool = False)

Bases: InputParams

Configuration parameters for GenesysAudioHookSerializer.

Parameters:

• genesys_sample_rate – Sample rate used by Genesys (default: 8000 Hz).

• sample_rate – Optional override for pipeline input sample rate.

• channel – Which audio channels to process (external, internal, both).

• media_format – Audio format (PCMU or L16).

• process_external – Whether to process external (customer) audio.

• process_internal – Whether to process internal (agent) audio.

• supported_languages – List of language codes the bot supports (e.g., [“en-US”, “es-ES”]).

• selected_language – Default language code to use.

• start_paused – Whether to start the session in paused state.

• ignore_rtvi_messages – Inherited from base FrameSerializer, defaults to True.

genesys_sample_rate: int

sample_rate: int | None

channel: AudioHookChannel

media_format: AudioHookMediaFormat

process_external: bool

process_internal: bool

supported_languages: list[str] | None

selected_language: str | None

start_paused: bool

__init__(params: InputParams | None = None, **kwargs)

Initialize the GenesysAudioHookSerializer.

Parameters:

• params – Configuration parameters.

• **kwargs – Additional arguments passed to BaseObject (e.g., name).

property session_id: str

Get the Genesys AudioHook session ID generated by the serializer.

property conversation_id: str | None

Get the Genesys conversation ID.

property is_open: bool

Check if the AudioHook session is open.

property is_paused: bool

Check if audio streaming is paused.

property participant: dict[str, Any] | None

Get participant info (ani, dnis, etc.) from the open message.

property input_variables: dict[str, Any] | None

Get custom input variables from the open message.

property output_variables: dict[str, Any] | None

Get custom output variables to send back to Genesys.

set_output_variables(variables: dict[str, Any]) → None

Set custom output variables to send back to Genesys on close.

These variables will be included in the ‘closed’ response when Genesys closes the connection, making them available in the Architect flow.

Parameters:

variables – Dictionary of custom variables to send to Genesys.

Example:

# During the conversation, collect data and set it
serializer.set_output_variables({
    "intent": "billing_inquiry",
    "customer_verified": True,
    "summary": "Customer asked about their bill",
    "transfer_to": "billing_queue"
})

async setup(frame: StartFrame)

Sets up the serializer with pipeline configuration.

Parameters:

frame – The StartFrame containing pipeline configuration.

create_opened_response(start_paused: bool = False, supported_languages: list[str] | None = None, selected_language: str | None = None) → dict[str, Any]

Create an ‘opened’ response message for the client.

This should be sent in response to an ‘open’ message from Genesys.

Parameters:

• start_paused – Whether to start the session paused.

• supported_languages – List of supported language codes.

• selected_language – The selected language code.

Returns:

Dictionary of the opened response message.

create_closed_response(output_variables: dict[str, Any] | None = None) → dict[str, Any]

Create a ‘closed’ response message.

This should be sent in response to a ‘close’ message from Genesys.

Parameters:

output_variables – Optional custom variables to pass back to Genesys. These will be available in the Architect flow after the AudioHook action completes.

Returns:

Dictionary of the closed response message.

Example:

# Pass custom data back to Genesys
serializer.create_closed_response(
    output_variables={
        "intent": "billing_inquiry",
        "customer_verified": True,
        "summary": "Customer asked about their bill"
    }
)

create_pong_response() → dict[str, Any]

Create a ‘pong’ response message.

This should be sent in response to a ‘ping’ message from Genesys.

Returns:

Dictionary of the pong response message.

create_resumed_response() → dict[str, Any]

Create a ‘resumed’ response message.

This should be sent in response to a ‘pause’ message when ready to resume.

Returns:

Dictionary of the resumed response message.

create_barge_in_event() → dict[str, Any]

Create a barge-in event message.

This notifies Genesys Cloud that the user has interrupted the bot’s audio output. Genesys will stop any queued audio playback.

Returns:

Dictionary of the barge-in event message.

create_disconnect_message(reason: str = 'completed', action: str = 'transfer', output_variables: dict[str, Any] | None = None, info: str | None = None) → dict[str, Any]

Create a ‘disconnect’ message to initiate session termination.

Parameters:

• reason – Disconnect reason (e.g., “completed”, “error”).

• action – Action to take (“transfer” to agent, “finished” if completed).

• output_variables – Custom output variables to pass back to Genesys.

• info – Optional additional information.

Returns:

Dictionary of the disconnect message.

create_error_message(code: int, message: str, retryable: bool = False) → dict[str, Any]

Create an ‘error’ message.

Parameters:

• code – Error code.

• message – Error message.

• retryable – Whether the operation can be retried.

Returns:

Dictionary of the error message.

async serialize(frame: Frame) → str | bytes | None

Serializes a Pipecat frame to Genesys AudioHook format.

Handles conversion of various frame types to AudioHook messages: - AudioRawFrame -> Binary PCMU audio data (resampled to 8kHz) - EndFrame/CancelFrame -> Disconnect message (JSON) - InterruptionFrame -> Barge-in event (JSON) - OutputTransportMessageFrame -> Pass-through JSON

Parameters:

frame – The Pipecat frame to serialize.

Returns:

Serialized data as string (JSON) or bytes (audio), or None if the frame type is not handled or session is not open.

async deserialize(data: str | bytes) → Frame | None

Deserializes Genesys AudioHook data to Pipecat frames.

Handles: - Binary data -> InputAudioRawFrame (converted from PCMU to PCM) - JSON ‘open’ -> OutputTransportMessageUrgentFrame with ‘opened’ response - JSON ‘close’ -> OutputTransportMessageUrgentFrame with ‘closed’ response - JSON ‘ping’ -> OutputTransportMessageUrgentFrame with ‘pong’ response - JSON ‘pause’ -> Sets is_paused=True, returns None - JSON ‘dtmf’ -> InputDTMFFrame - JSON ‘update’ -> Updates participant info, returns None - JSON ‘error’ -> Logs error, returns None

Protocol responses (opened, closed, pong) are returned as urgent frames to be sent immediately through the transport.

Parameters:

data – The raw WebSocket data from Genesys (binary audio or JSON text).

Returns:

A Pipecat frame to process, or None if handled internally.