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)[source]

Bases: StrEnum

AudioHook protocol message types.

The server (Pipecat) sends pause and resume to ask Genesys to pause or resume the audio stream. Genesys sends paused and resumed when the stream actually pauses or resumes, whether the server asked or Genesys decided on its own.

OPEN = 'open'
OPENED = 'opened'
CLOSE = 'close'
CLOSED = 'closed'
PAUSE = 'pause'
PAUSED = 'paused'
RESUME = 'resume'
RESUMED = 'resumed'
DISCARDED = 'discarded'
PING = 'ping'
PONG = 'pong'
UPDATE = 'update'
EVENT = 'event'
ERROR = 'error'
DISCONNECT = 'disconnect'
class pipecat.serializers.genesys.AudioHookChannel(*values)[source]

Bases: StrEnum

AudioHook audio channel configuration.

EXTERNAL = 'external'
INTERNAL = 'internal'
BOTH = 'both'
class pipecat.serializers.genesys.AudioHookMediaFormat(*values)[source]

Bases: StrEnum

Supported audio formats.

PCMU = 'PCMU'
L16 = 'L16'
class pipecat.serializers.genesys.GenesysAudioHookSerializer(params: InputParams | None = None, **kwargs)[source]

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

While Genesys has paused the stream, audio is dropped in both directions. Genesys pauses on its own (for example during a hold) or when asked with create_pause_request(), and resumes the same way with create_resume_request().

Event handlers available:

  • on_open: Called when Genesys opens the session. Args: (message: dict)

  • on_close: Called when Genesys closes the session. Args: (message: dict)

  • on_ping: Called when Genesys sends a ping. Args: (message: dict)

  • on_paused: Called when Genesys pauses the audio stream. Args: (message: dict)

  • on_resumed: Called when Genesys resumes the audio stream. Args: (message: dict)

  • on_update: Called when Genesys sends an update. Args: (message: dict)

  • on_error: Called when Genesys reports an error. Args: (message: dict)

  • on_dtmf: Called when Genesys sends a DTMF digit. Args: (message: dict)

  • on_pause: Called when Genesys pauses the audio stream. Args: (message: dict)

    Deprecated since version 1.16.0: Use on_paused instead. Will be removed in 2.0.0.

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,
        # Send audio in 200 ms packets; Genesys rate-limits incoming messages
        audio_out_10ms_chunks=20,
    ),
)

# 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})

# Resume a session opened with start_paused=True
await worker.queue_frame(
    OutputTransportMessageUrgentFrame(message=serializer.create_resume_request())
)
Parameters:

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

PROTOCOL_VERSION = '2'
class InputParams(*, ignore_rtvi_messages: bool = True, resampler_clear_after_secs: float | None = 0.2, 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)[source]

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 Genesys starts the audio stream paused. Send GenesysAudioHookSerializer.create_resume_request() to start it.

  • 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)[source]

Initialize the GenesysAudioHookSerializer.

Parameters:
  • params – Configuration parameters.

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

add_event_handler(event_name: str, handler)[source]

Add an event handler for the specified event.

Parameters:
  • event_name – The name of the event to handle.

  • handler – The function to call when the event occurs.

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

Whether Genesys has paused the audio stream.

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[source]

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(setup: FrameProcessorSetup)[source]

Sets up the serializer with pipeline configuration.

Parameters:

setup – Configuration object containing setup parameters.

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

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][source]

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][source]

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_pause_request() → dict[str, Any][source]

Create a ‘pause’ message asking Genesys to pause the audio stream.

Genesys answers with a ‘paused’ message, which pauses the session.

Returns:

Dictionary of the pause message.

create_resume_request() → dict[str, Any][source]

Create a ‘resume’ message asking Genesys to resume the audio stream.

Genesys answers with a ‘resumed’ message, which resumes the session. Send it to start a session opened with start_paused=True.

Returns:

Dictionary of the resume message.

create_resumed_response() → dict[str, Any][source]

Create a ‘resume’ message asking Genesys to resume the audio stream.

Deprecated since version 1.16.0: Use create_resume_request() instead. Will be removed in 2.0.0.

Returns:

Dictionary of the resume message.

create_barge_in_event() → dict[str, Any][source]

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][source]

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][source]

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[source]

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[source]

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 ‘paused’ -> Sets is_paused=True, returns None - JSON ‘resumed’ -> Sets is_paused=False, 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.