> For the complete documentation index, see [llms.txt](https://docs.ixhello.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ixhello.com/ixhc2/integrations/genesys-integration-setup-with-ix-hello-customer-v2.md).

# Genesys Integration Setup with iX Hello Customer v2

### Overview

The Genesys Audio Connector enables iX Hello Customer v2 to integrate with Genesys Cloud as a third-party AI voice bot. In this integration model, Genesys Cloud continues to manage inbound and outbound calls, while Customer v2 handles the conversational AI experience.

Instead of relying on SIP/BYOC truncking and transfer-based integrations, Customer v2 operates as a secure WebSocket (WSS) server, allowing Genesys to stream live audio directly to the Customer v2 bot through the Genesys Audio Connector.

This approach provides a simpler, more reliable, and scalable method for connecting Customer v2 conversational flows with Genesys call flows.

***

## Architecture Overview

Customer\
│\
▼\
Genesys Cloud\
│\
▼\
Genesys Architect Flow\
│\
▼\
Call Audio Connector Action\
│\
▼\
Genesys Audio Connector\
(WebSocket/WSS)\
│\
▼\
iX Hello Customer v2 Flow\
│\
▼\
Bot Conversation\
(STT → NLU → TTS)\
│\
▼\
Return Intent / Summary / Context\
│\
▼\
Genesys Architect Flow\
│\
▼\
Live Agent / Queue / Next Action

***

## How It Works

1. A customer places a call to Genesys Cloud.
2. Genesys Architect receives and manages the call.
3. A Call Audio Connector action routes the conversation to a configured Customer v2 flow.
4. Genesys establishes a secure WebSocket connection with Customer v2 using the Genesys Audio Connector.
5. Audio is streamed bidirectionally between Genesys and Customer v2.
6. The Customer v2 bot processes the conversation and interacts with the caller.
7. When the conversation ends, Customer v2 returns conversation context such as:
   * Customer intent
   * Summary
   * Account information
   * Custom variables
8. Genesys Architect resumes execution and uses the returned information to determine the next workflow action, such as:
   * Transfer to an agent
   * Route to a queue
   * Update participant attributes
   * Perform follow-up automation

***

## Business Value

### Reduced Infrastructure Complexity

* Eliminates SIP trunks and BYOC configurations.
* Removes RTP media management requirements from the Customer v2 platform.
* Simplifies deployment and maintenance.

### Improved Reliability

* Uses secure WebSocket (WSS) communication over port 443.
* Simplifies firewall and networking requirements.
* Provides secure and direct audio streaming.

### Seamless Call Hand-Off

* Genesys Architect continues to control the call lifecycle.
* Customer v2 focuses solely on AI-powered conversations.
* Information collected by the bot can be used for agent routing or escalation.

### Native Context Sharing

* Session variables are exchanged through the AudioHook protocol.
* Supports passing information such as:
  * Customer ID
  * Account ID
  * Intent
  * Conversation summary
  * Custom business data
* Eliminates manual UUI parsing requirements.

***

## Key Features

### Audio Hook WebSocket Server

Customer v2 implements the Genesys AudioHook Protocol (v2) through the channel gateway service, enabling direct communication with Genesys Cloud.

### Real-Time Bidirectional Audio

Supports:

* PCMU 8kHz audio streaming
* Speech-to-Text (STT)
* Natural Language Understanding (NLU)
* Text-to-Speech (TTS)

### Session Variable Mapping

Allows:

* Architect variables → Customer v2 variables
* Customer v2 variables → Architect variables

Data can be exchanged at both the beginning and end of a conversation.

### Secure Authentication

Supports:

* API Key authentication
* HMAC Signature verification
* Organization-level authorization

***

### Step 1: Obtain the Genesys Organization ID

* Log in to Genesys Cloud.
* Navigate to:

  Admin → Organization Settings

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FZYUP4XROlT2JHBFS3QlD%2Fimage.png?alt=media&amp;token=9cfdd172-3922-46d6-b29b-55073075869c" alt=""><figcaption></figcaption></figure>

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FFZyhUu8C4YD4e9kKzLH1%2Fimage.png?alt=media&amp;token=c8501bf9-5802-49cb-912e-eed372f788c5" alt=""><figcaption></figcaption></figure>

* Copy the Genesys Organization ID.

This Organization ID is required for validation within customer v2.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FJuc2ZeChMkInODx3qhyG%2Fimage.png?alt=media&amp;token=10379bf9-114b-4f8c-8995-d245d1b26c56" alt=""><figcaption></figcaption></figure>

***

### Step 2: Configure the Genesys Organization in Customer v2

* Log in to iX Hello Customer v2.
* Navigate to:

  Settings → Genesys Cloud Integration
* Click Add Organization.
* Enter the copied Genesys Organization ID.
* Save the configuration.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FRcjJG4g6GFgVxs6pGhXg%2Fimage.png?alt=media&amp;token=c93d00da-16f0-4f4e-99e9-11e97d1e394d" alt=""><figcaption></figcaption></figure>

This serves as the second-level validation during call initiation.

***

### Step 3: Obtain API Credentials

To obtain credentials:

* Contact the Support Team.
* Request:
  * API Key
  * Organization Details
  * Endpoint Information

{% hint style="info" %}
Note: Most users may not have direct AWS access and must obtain the credentials through the Support Team by rising a ticket on Solvnow
{% endhint %}

***

### Step 4: Configure the Audio Connector in Genesys

* Navigate to:

  **Admin → Integrations**

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FXkPEjX6qpl22R9g23QSY%2Fimage.png?alt=media&amp;token=f9f003ef-2ac0-413c-8c9a-730537427595" alt=""><figcaption></figcaption></figure>

* Open the configured **Audio Connector**.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2F99W4QxmnnazBLwmrnr49%2Fimage.png?alt=media&amp;token=93530f6b-2d69-40b3-8240-451336b1308f" alt=""><figcaption></figcaption></figure>

* Select the **Configuration** tab.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FF33MZluYE5xI2tiWhslt%2Fimage.png?alt=media&amp;token=024c3429-9499-4ee4-b38f-78d1ba119dde" alt=""><figcaption></figcaption></figure>

* Under **Credentials**, provide:

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2F3x9HTxslowQd6Nf2YkjC%2Fimage.png?alt=media&amp;token=85b77411-5c65-46a9-b779-6a7ee57521f6" alt=""><figcaption></figcaption></figure>

#### API Key

* Enter the API key supplied by the customer v2 team.

#### Client Secret

* Currently, client secret validation is not enforced.
* You may provide any value if required.
* Navigate to the AWS Access Portal. Under the Accounts section, locate the account you created and select Open to access the account.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2Fe1DFixzGA0fjAaxzzkda%2Fimage.png?alt=media&amp;token=639736b4-0d1f-4d9e-9262-45b88ec030ea" alt=""><figcaption></figcaption></figure>

* Navigate to AWS secrets manager -> secrets -> search for Headless API associated.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FDuP9cS5JYKKJ6VP9Sjay%2Fimage.png?alt=media&amp;token=d1bce219-e057-4e94-8d04-be98caa52772" alt=""><figcaption></figcaption></figure>

* Click open the Headless API associated with the account and scroll down to secrets value section, copy the secret key and secret value.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FKxlKqHQXyACnGtbtZZ0z%2Fimage.png?alt=media&amp;token=448c8c55-cd1d-4e7d-b6ef-69f774a3266d" alt=""><figcaption></figcaption></figure>

* Once you have the secret key and secret value, navigate to Genesys and update the API key and the secret key.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FDdymGgEzpNolNXbTf5AQ%2Fimage.png?alt=media&amp;token=34b1997e-752c-42ca-b195-a4034317324c" alt=""><figcaption></figcaption></figure>

***

### Step 5: Configure the WebSocket URL

* Log-in to the customer v2 platform.
* Locate the WebSocket endpoint associated with the organization.
* Copy the WebSocket URL.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FTqoZopN3EiXTqrDzYUoB%2Fimage.png?alt=media&amp;token=87a5e053-9043-49e3-abe3-58bca61ce2cf" alt=""><figcaption></figcaption></figure>

* Paste the URL into the Audio Connector configuration in Genesys.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2F5h2qJlInz3YbmoqqBe0h%2Fimage.png?alt=media&amp;token=1f750d26-2e7d-4664-bea0-cec7d6278200" alt=""><figcaption></figcaption></figure>

Important

* Each WebSocket endpoint is organization specific.
* Ensure the endpoint corresponds to the correct customer v2 organization.

***

### Step 6: Configure the Flow

A customer v2 flow must exist before Genesys can invoke it.

### Obtain the Flow ID

* Navigate to the Flows section in customer v2.
* Locate the required flow.
* Copy the Flow ID.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FvBbpcu6iDXjKmlpr0bjH%2Fimage.png?alt=media&amp;token=3e06b831-c37c-4229-9c98-dd7169b09d42" alt=""><figcaption></figcaption></figure>

***

### Step 7: Configure the Flow ID in Genesys

Within the Audio Connector configuration:

* Locate the Flow Configuration section.
* Enter the customer v2 Flow ID.
* Save the changes.

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2FYyGAvUYhjJa3nKh9iIww%2Fimage.png?alt=media&amp;token=042bb3af-430b-4ee0-b72f-f99d311b6d33" alt=""><figcaption></figcaption></figure>

***

## Required Configuration Parameters

The following parameters are mandatory for successful integration:

| Configuration           | Purpose                     |
| ----------------------- | --------------------------- |
| API Key                 | Authentication              |
| Genesys Organization ID | Authorization validation    |
| iX Organization ID      | API access identification   |
| WebSocket URL           | Real-time communication     |
| Flow ID                 | Target customer v2 bot flow |

***

## Making a Test Call

* Save all configurations.
* Publish the Genesys inbound call flow.
* Initiate a test call.

Expected flow:

<figure><img src="https://4187494610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFe4cpY1jy0FJ4kgC7wSx%2Fuploads%2Fntzxljsn6pgB7kk1BGO2%2Fimage.png?alt=media&amp;token=ff921b82-ec3b-4216-9003-31a5934b5829" alt="" width="337"><figcaption></figcaption></figure>

***

## Failure Scenarios

**Invalid API Key**

**Result:**

* Authentication fails.
* Call is immediately rejected.

***

### Invalid Genesys Organization ID

**Result:**

* Organization validation fails.
* Call is disconnected.

***

### Missing Organization Mapping in customer v2

**Result:**

* customer v2 cannot authorize the request.
* Call fails before bot invocation.

***

#### PII Redaction <a href="#pii-redaction" id="pii-redaction"></a>

Before data is returned to Genesys:

1. Conversation summaries are generated.
2. PII Redaction Service processes the content.
3. Sensitive information is masked according to configured policies.

***

#### Model Selection <a href="#model-selection" id="model-selection"></a>

Flow designers can select the preferred LLM for:

* Summarization
* Intent detection
* Conversation understanding

Examples:

* GPT-4o-mini
* Other supported models

Model selection allows optimization of both performance and cost.<br>

***

### Conclusion

The Genesys Cloud and iX Hello Customer (V2) integration enables secure real-time voice communication by validating requests through multiple authorization checks before a call is connected to a V2 bot. Successful integration requires the correct configuration of the API Key, Genesys Organization ID, iX Organization ID, WebSocket Endpoint, and Flow ID. Once these components are configured and validated, Genesys can seamlessly route calls to the designated V2 flow, allowing callers to interact with AI-powered voice bots in real time. Any mismatch in the credentials or organization mappings results in immediate call failure, ensuring that only authorized organizations can access the service. This layered validation approach provides a secure, reliable, and scalable integration between Genesys Cloud and the V2 platform.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ixhello.com/ixhc2/integrations/genesys-integration-setup-with-ix-hello-customer-v2.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
