> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Genesys

[Back to messaging or digital channels](https://koreai.mintlify.site/agent-platform/channels.md#messaging-or-digital-channels)

Connect your agent to Genesys Cloud as a Bot Connector, so an Architect flow hands each conversation turn to it. You install the Bot Connector integration in Genesys, bind its Stream ID and a shared secret to Artemis, then call the integration from an Architect flow.

The setup requires:

1. [Genesys Cloud setup](#genesys-cloud-setup): install the Bot Connector integration and copy its Stream ID.
2. [Artemis channel configuration](#artemis-channel-configuration): create the connection, then copy its Webhook URL.
3. [Bot Connector configuration in Genesys](#bot-connector-configuration-in-genesys): set the URL and secret, activate the integration, and call it from Architect.
4. [Verify the connection](#verify-the-connection) end to end.

After setup, an Architect flow that reaches **Call Bot Connector** sends the turn to Artemis. The agent answers inside the same HTTP request, and Architect branches on the returned intent.

**Important considerations**

* **The response travels in the same request**: Genesys holds one POST open while the agent runs, then reads the reply from that response. There's no callback or later send API, so the channel stays synchronous and non-streaming.
* **Client Secret isn't a Genesys OAuth secret**: It's a pre-shared ingress token you generate and enter identically on both sides. An OAuth integration secret fails unless Genesys sends that same value on webhook requests.
* **Bot Connector needs a subscription change**: Contact Genesys Cloud Sales before you can install the integration. Genesys allows up to five Bot Connector integrations per organization.
* **Architect intents must already exist**: Artemis returns intent names that Architect matches to branches. Artemis doesn't create or validate them.

## Prerequisites

Confirm these before you start.

* A Genesys Cloud organization with Bot Connector on its subscription, in the region that owns the Architect flow.
* Genesys Cloud admin access, with permission to install integrations and edit Architect flows.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## How Artemis routes Bot Connector requests

Genesys posts to a URL that ends with the Stream ID. Artemis resolves the connection from that path segment and the session from the payload.

| Piece | Owner | What it does |
| - | - | - |
| **Stream ID** | Genesys | Routes requests. Artemis reads the final `/hooks/{streamId}` path segment and matches it to an active connection. It's a routing identifier, not a secret. |
| **Client Secret** | You | Authenticates each request. Artemis compares the received token with the encrypted secret using a timing-safe check. |
| `genesysConversationId` | Genesys | Identifies each end-user session inside the connection. Reusing it continues the conversation, and changing it starts a new one. |
| **Webhook URL** | Artemis | Receives the Bot Connector POST. It ends with the encoded Stream ID. |

***

## Genesys Cloud setup

Do this in Genesys Cloud before you open Artemis. Select **Open Genesys Cloud** in the setup guide to jump straight there. Genesys documents the same screens in [Configure the Genesys Bot Connector integration](https://help.genesys.cloud/articles/configure-the-genesys-bot-connector-integration/).

**1. Sign in to the right region and organization**

Sign in to the organization and regional domain that own the Architect flow. Don't point a development organization's integration at production Artemis.

**2. Install the Bot Connector integration**

1. Go to **Admin** > **Integrations** > **Integrations**. On newer navigation, go to **Menu** > **IT and Integrations** > **Integrations**.
2. Find the **Genesys Bot Connector** tile and select **Install**.
3. On the **Details** tab, name the integration for the agent and environment.

Don't install **Genesys Digital Bot Connector**. It's a separate integration with its own Architect action. Keep this integration separate from Open Messaging and Audio Connector integrations too.

**3. Copy the Stream ID**

Copy the Bot Connector Stream ID exactly, with no surrounding whitespace. It becomes the routing identifier in Artemis and the last segment of the webhook URL.

**4. Generate a Client Secret**

Create a high-entropy random string, and store it in your secret manager. Use a different secret per environment.

***

## Artemis channel configuration

Create the connection before Genesys sends its first request. Artemis must resolve the Stream ID and the encrypted secret before it can authenticate and run a request.

1. Open Artemis and select the project.

2. Go to **Deployments** > **Channels** > **Genesys** > **+ New**. The **New Genesys Connection** dialog opens, with the setup guide on the left and the fields on the right.

3. Configure the fields:

   | Artemis field | Source / Notes | What it controls |
   | - | - | - |
   | **Display Name** | You choose it | The label operators see. Name it for the Genesys organization and environment. Routing ignores it. |
   | **Stream ID** | The Bot Connector integration | The routing key. Don't enter the organization ID, integration ID, OAuth client ID, conversation ID, or Architect flow ID. |
   | **Client Secret** | The token you generated | Authenticates each request. Enter the same value in the Genesys integration. |
   | **Environment** | Your published environments | The environment whose active deployment answers the Architect flow. Leave the working copy default only while you develop. |
   | **Provider Verification Strength** | Defaults to **Weak** | How far the runtime trusts Genesys's identity assertion when it links a user to an existing session. Choose **Strong** only when you base continuity and account-linking decisions on it. |
   | **Initial Status** | Defaults to **Active** | Keep it **Active**. An inactive connection returns not found even when the URL is right. |

4. Select **Create**.

5. Open the connection and copy the **Webhook URL** from the summary panel. Keep the encoded Stream ID at the end. The generic `/genesys/hooks` path can't select a connection.

***

## Bot Connector configuration in Genesys

Return to the integration and finish it with the Artemis values, then call it from a flow.

**1. Set the Bot Connector URL**

On the integration's **Configuration** tab, set the Bot Connector URL to the Artemis **Webhook URL**. Use the public HTTPS runtime origin.

**2. Add the shared secret**

On the **Credentials** tab, enter the same Client Secret as the bearer token.

| Header | Use |
| - | - |
| `Authorization: Bearer` | Preferred |
| `x-channel-secret`, `x-ingress-secret`, `x-webhook-secret` | Also accepted |

Artemis never accepts a token in the query string.

**3. Activate the integration**

Set the integration status to active. An inactive integration never appears in Architect.

**4. Add the Call Bot Connector action**

1. Open the Architect flow that should reach the agent.
2. Add or select a **Call Bot Connector** action, and point it at this integration.
3. Connect the failure path to real handling.

Architect takes the failure path on execution and connectivity errors, and after four consecutive turns return an unchanged intent. See [Call Bot Connector action](https://help.genesys.cloud/articles/call-bot-connector-action/).

**5. Validate before you publish**

Run Architect validation and test on a non-production interaction. Publish only after you confirm the URL, secret, response timing, and failure branches.

### Validation checklist

Work down this list once per connection.

| Validation item | Expected result |
| :- | :- |
| Install the integration | Bot Connector installed and named distinctly, in the region that owns the flow. |
| Create the Artemis connection | Saved as **Active** with the exact Stream ID and the shared secret. |
| Configure the integration | Webhook URL and matching secret saved, and the integration active. |
| Map the Architect outcomes | Intent names match branches that exist in the flow. |
| Wire the Architect action | **Call Bot Connector** points at this integration, with the failure path connected. |
| Run a test interaction | A turn reaches the agent, and Architect branches on the returned intent. |

***

## Map Architect outcomes

Artemis returns an intent name with each reply, and Architect branches on it. Configure the mapping on the **Configuration** tab under **Architect outcome mapping**.

1. Turn on **Enable terminal intent mapping**.
2. For each outcome, select a **Value source** and enter the **Genesys Architect intent name**.
3. Select **Save Changes**.

| Outcome | When Artemis returns the intent |
| - | - |
| **Continue conversation** | On ongoing replies 1, 4, 7, and every third reply after that. Other ongoing replies omit the intent. |
| Escalate to an agent | On any turn that escalates. |
| Close the session | On any turn that ends the session. |

**Value source** takes a literal intent name or a project variable. Use a project variable when one agent serves several flows with different intent names. Only non-secret project variables qualify. Select **Open project variables** to create one.

> [!WARNING]
>
> Matching intents and Architect branches must already exist in Genesys Cloud. A typo produces a branch Architect never takes, without an error.

***

## Verify the connection

Test the failure modes as well as the happy path, because Architect branches on the status Artemis returns.

1. Send `inputMessage.type=Text` with a unique message and a stable `genesysConversationId`. Confirm HTTP `200` and one Text reply in `replymessages`.
2. Send a second turn with the same `genesysConversationId`. Confirm it resumes the same `genesys:{conversationId}` session, and that a different ID starts a new one.
3. Return an authored button, send its encoded payload in `inputMessage.buttonResponse.payload`, and confirm the session resumes with the right action value.
4. Confirm a wrong secret returns `401`, an unknown or inactive Stream ID returns `404`, and malformed input returns `400`.
5. Confirm the Architect flow handles `503` busy and execution failures without looping.

***

## Request and response contract

Genesys carries the whole turn in one exchange.

| Direction | Content |
| - | - |
| Request | Always `genesysConversationId` and `inputMessage.type`. Text turns add `inputMessage.text`. Structured quick replies add `inputMessage.buttonResponse.payload`. |
| Response | `replymessages`, `botState`, `intent`, and `endOfTask`. A normal reply carries one `replymessages` entry of type Text. |
| Quick replies | Authored buttons become a Structured reply with QuickReply entries. Each payload encodes the action ID and value. |
| Defaults | `botState` `MOREDATA`, intent `Default Kore VA Intent`, and `endOfTask` `false`, unless outcome mapping applies. |
| Media | The channel doesn't process inbound media or send media responses. |

***

## Security and operational boundaries

HTTPS and the shared token protect the endpoint.

* **Secret per environment**: Use a unique, high-entropy Client Secret for each environment. Store it only in the Genesys integration's credentials and in Artemis.
* **One authorization header**: Prefer `Authorization: Bearer`. If your ingress uses another supported header, make sure it preserves that header and strips untrusted duplicates.
* **Stream ID is public**: Treat it as a routing value. Never put the token in the URL or in logs.
* **Session metadata**: Optional `sessionMetadata` crosses a trust boundary, and Artemis validates it before the agent runs. Send only the expected JSON object shape.
* **Separate environments**: Use separate integrations, Stream IDs, secrets, Architect flows or versions, and connections for development and production.

***

## Manage the channel connection

Open a connection from **Deployments** > **Channels** > **Genesys** to manage it. The page has a header, three tabs, and a summary panel on the right.

**Header.** Shows the connection name, its environment badge, its status, and when it last changed. The **...** overflow menu holds the connection-level actions.

**Summary panel.** Stays visible on every tab.

| Field | Description |
| - | - |
| **Channel** and **Connection Type** | Read **Genesys** and **Channel Connection**. |
| **Identifier** | The Stream ID this connection routes on. Compare it with the integration's Stream ID when requests return `404`. |
| **Credentials** | Reads **Configured** once credentials save. |
| **Webhook URL** | The Bot Connector URL for Genesys, with a copy control. |
| **Created** and **Updated** | Date and time of creation and of the last change. |

> [tab] Credentials
>
> Artemis encrypts the secret after you save it. Leave the field blank to keep the current value, or enter a new one to replace it.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Turn it on, then select a saved auth profile in place of the field below. |
> | **Client Secret** | The shared token. Change it here and in the Genesys integration together, because Artemis rejects requests when the values differ. |
>
> Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update how the connection behaves. **Genesys Settings** holds the provider-specific fields.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see. |
> | **Provider Verification Strength** | How far the runtime trusts Genesys's identity assertion. |
> | **Stream ID** | Read-only, with a copy control. To serve a different integration, create a new connection. |
> | **Message template** | The authorization message the connection sends when a tool needs the user to authorize. Insert variables from the chips, select **Show more** for the full list, and select **Show preview** to check it. |
> | **Webhook URL** | The Bot Connector URL, with a copy control. |
> | **Architect outcome mapping** | The intent names Artemis returns. See [Map Architect outcomes](#map-architect-outcomes). |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers the Architect flow.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it. |
>
> Select **Save Changes** after you switch the environment.

***

## Troubleshoot connection issues

Match the status code first. Most failures trace to the Stream ID, the secret, or the conversation ID.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Webhook returns `404` | Stream ID mismatch, or the connection isn't active | Confirm the URL ends with the exact Stream ID, check for copied whitespace, and confirm the connection is **Active** in the intended project. |
| Webhook returns `401` | Token mismatch or conflicting headers | Send the exact Client Secret through `Authorization: Bearer` or a supported header, remove duplicate auth headers, and confirm nobody rotated the secret on one side only. |
| Webhook returns `400` | A required field is missing | Include a non-empty `genesysConversationId` and `inputMessage.type`. Text turns need `inputMessage.text`, and Structured actions need `buttonResponse.payload`. |
| Webhook returns `503` busy | Concurrent turns for one session | Serialize turns within a conversation, and retry according to the Architect failure policy. |
| Genesys times out before a response | Agent execution outlasts the provider timeout | Compare the provider timeout with execution duration, and check model and tool latency. |
| Text works but quick replies don't | Missing QuickReply entries or a lost payload | Confirm the response contains Structured QuickReply entries and that the encoded payload returns as `buttonResponse.payload`. |
| Conversation context resets | The conversation ID changes between turns | Keep the same `genesysConversationId` for every turn, and never replace it with the Stream ID or a request ID. |
| Architect never takes the expected branch | The intent name doesn't exist in the flow | Compare **Architect outcome mapping** with the intents and branches in Architect. |
| The integration doesn't appear in Architect | The integration isn't active | Activate it in Genesys Cloud, then reopen the flow. |

***

## Genesys reference

Use these pages when you need detail beyond what this article covers.

| Resource | Use it for |
| - | - |
| [About Genesys Bot Connector](https://help.genesys.cloud/articles/about-genesys-bot-connector/) | What the connector supports. |
| [Configure the Genesys Bot Connector integration](https://help.genesys.cloud/articles/configure-the-genesys-bot-connector-integration/) | Installing and activating the integration. |
| [Call Bot Connector action](https://help.genesys.cloud/articles/call-bot-connector-action/) | Action inputs, timeouts, error types, and failure paths. |
| [About Genesys Digital Bot Connector](https://help.genesys.cloud/articles/about-genesys-digital-bot-connector/) | Telling the two connectors apart. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up Genesys Open Messaging](https://koreai.mintlify.site/agent-platform/channels/genesys-open-messaging)
* [Set up Zendesk](https://koreai.mintlify.site/agent-platform/channels/zendesk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.