> ## 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 Open Messaging

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

Connect your agent to Genesys Cloud Open Messaging through a project-scoped, signed webhook. You bind a Genesys Open Messaging integration and an Auth Profile to the connection, validate the path in diagnostics mode, then enable live conversations.

The setup requires:

1. [Prepare Genesys Cloud](#prepare-genesys-cloud) and its authentication.
2. [Artemis channel configuration](#artemis-channel-configuration): create the connection and copy its reveal-once values.
3. [Webhook configuration in Genesys](#webhook-configuration-in-genesys): set the signed webhook, or provision it from Artemis.
4. [Validate and enable](#validate-and-enable) the connection.

After setup, Genesys posts each customer message to Artemis. Artemis verifies the signature, queues the message, and sends the agent's reply back through the Genesys Platform API.

**Important considerations**

* **The connection token selects the connection**: Artemis hashes the final `/webhooks/{connectionToken}` path segment and matches it to the project connection. The generic webhook path can't select a connection.
* **Three values, three jobs**: The connection token routes inbound requests. The signature secret proves the request body came from the integration. The Integration ID identifies the integration for outbound calls.
* **The full endpoint is reveal-on-create**: Artemis stores the token only as a SHA-256 hash and redacts credentials after creation. If you lose the plaintext token, create a new connection.
* **Start in diagnostics mode**: **Diagnostics only** permits setup checks without running live conversations. Switch to **Enabled** only after every check passes.

## Prerequisites

Confirm these before you start.

* Genesys Cloud admin access in the organization that owns the Open Messaging integration.
* A Genesys OAuth client that can send Open Messaging inbound messages, structured responses, and receipts.
* Artemis project access with permission to open **Deployments** > **Channels**, and a deployed agent in the environment you intend to bind.

***

## Prepare Genesys Cloud

Do this before you open the Artemis dialog. Select **Open Genesys Cloud** in the setup guide to jump straight there.

**1. Select the owning region and organization**

Sign in to the regional Genesys Cloud organization that owns the Open Messaging integration. Artemis uses the region to select the matching Genesys Platform API host.

**2. Create or identify the Open Messaging integration**

In Genesys Cloud Admin, create or select the Open Messaging integration and copy its **Integration ID**.

Don't substitute a Bot Connector Stream ID, an Audio Connector integration, an organization ID, or an OAuth client ID.

**3. Create a Genesys Auth Profile**

In Artemis, create a project integration Auth Profile for connector `genesys`, using OAuth 2.0 Client Credentials or Bearer authentication. Artemis uses it only for outbound Genesys Platform API calls.

**4. Grant only the permissions the integration needs**

The OAuth client must send Open Messaging inbound messages, structured responses, and receipts for this integration. Keep development and production clients, integrations, and profiles separate.

***

## Artemis channel configuration

Create the connection with the Genesys values. Artemis generates the webhook token and signature secret in the dialog.

1. Open Artemis and select the project.

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

3. Under **Open Messaging setup**, configure the provider fields:

   | Artemis field | What it controls |
   | - | - |
   | **Genesys Region** | The Genesys Platform API host. A wrong region can authenticate yet fail organization or integration lookups. |
   | **Genesys Organization ID** | The organization that owns the integration. Required. |
   | **Integration ID** | The Open Messaging integration. Artemis uses it as the external identifier for outbound calls. Required. |
   | **Activation Mode** | **Diagnostics only** runs setup checks but doesn't execute live inbound conversations. **Enabled** processes live traffic. **Disabled** turns the adapter off. Start with **Diagnostics only**. |
   | **Delivery Mode** | **External bridge** is the standard bot-facing channel. **Agent workflow** makes the connection available to the Genesys Open Messaging agent-transfer handoff. |
   | **Genesys Auth Profile** | The active Auth Profile for this organization and environment. Artemis accepts only active Genesys profiles using OAuth client credentials or Bearer authentication. Required. |
   | **Webhook Connection Token** | Generated. Routes inbound requests through the webhook URL. Keep the generated value unless an approved migration needs a replacement. |
   | **Webhook Signature Secret** | Generated. Verifies the HMAC signature on each inbound request. Keep the generated value unless an approved migration needs a replacement. |

4. Configure the common fields:

   | Artemis field | What it controls |
   | - | - |
   | **Display Name** | The label operators see. Routing ignores it. |
   | **Environment** | The environment whose active deployment answers messages. Leave the working copy default only while you develop. |
   | **Provider Verification Strength** | 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** | **Active** takes traffic immediately. **Inactive** saves the connection disabled until you activate it. |

5. Select **Create**.

6. Copy the full webhook endpoint and the signature secret from the confirmation screen before you close it.

***

## Webhook configuration in Genesys

Configure the signed webhook in the Open Messaging integration, or let Artemis provision it.

> [tab] Configure manually
>
> 1. Paste the full connection-specific HTTPS URL into the Genesys Open Messaging integration. Keep the final connection token.
> 2. Enter the Artemis **Webhook Signature Secret** as the integration's outbound webhook signature secret. Don't use the Genesys OAuth client secret or the connection token.
> 3. Confirm Genesys signs the exact raw request body with HMAC-SHA256, in a supported header and format.

> [tab] Provision from Artemis
>
> Use this path when the Genesys integration doesn't exist yet.
>
> 1. Verify the region, organization, Auth Profile, connection token, and signature secret on the connection.
> 2. On the **Testing** tab, run the provisioning action. Artemis creates the Genesys Open Messaging integration with the current webhook URL and signature secret.

Artemis accepts these signature headers and formats. The digest must cover the original request bytes before any JSON parsing or normalization.

| Accepted headers | Accepted formats |
| - | - |
| `X-Hub-Signature-256`, `X-Genesys-Signature-256`, `X-Genesys-Signature`, `X-Signature-256`, `X-Signature` | `sha256=<hex>`, raw lowercase `<hex>`, or `base64` |

***

## Validate and enable

Run every check in diagnostics mode, then switch to live traffic.

1. Open the connection's **Testing** tab and run the signature check on a signed fixture. This confirms the stored secret and signature format without sending provider traffic.
2. Run the inbound diagnostic. Confirm the adapter resolves the connection through the project runtime, normalizes the sender and conversation, and returns redacted provider metadata.
3. Run the receipt diagnostic. Confirm the Auth Profile obtains a token and calls the Genesys receipt endpoint for the configured Integration ID.
4. Change **Activation Mode** to **Enabled**, and confirm the connection status is **Active**.
5. Send a unique live text, a quick reply, and a follow-up in the same Genesys conversation.

***

## Messaging and delivery behavior

Artemis applies these rules to every Open Messaging conversation.

| Area | Behavior |
| - | - |
| Delivery | Asynchronous. Artemis authenticates and accepts each event, then sends the agent's reply through the Genesys Platform API. |
| Continuity | The Genesys conversation ID is the preferred key. Without it, Artemis falls back to the sender identity and hashes the session components. |
| Quick replies | Artemis sends authored quick replies through the Genesys structured-response endpoint. Return the selected payload unchanged. |
| Receipts | The adapter can send `DELIVERED` and `READ` receipts when the event and integration support them. |
| Media | The default mode is `metadata_only`. Artemis validates and summarizes media references, and downloads binary media only with an explicitly supported mode and allowlist. |
| Payload size | 65,536 bytes per inbound request by default. |

***

## Security and operational boundaries

The connection depends on a hashed token, an encrypted secret, and an Auth Profile.

* **Preserve raw bytes**: Pass the raw HTTP request through your ingress proxy unchanged. Re-serialized JSON changes the HMAC input and fails valid signatures.
* **Unique values per environment**: Use separate connection tokens and signature secrets for each environment. Never put OAuth client secrets in the webhook URL, or reuse the signature secret as an OAuth credential.
* **Credentials stay in the Auth Profile**: Keep Genesys OAuth credentials in the bound Auth Profile. Diagnostic and runtime responses redact provider metadata and never expose tokens or secrets.
* **Narrow media allowlists**: Reject oversized bodies before execution, and keep media host allowlists narrow when you enable downloads.

***

## Manage the channel connection

Open a connection from **Deployments** > **Channels** > **Genesys Open Messaging** to manage it. The page has a header, its 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 and shows the channel, connection type, identifier, credential status, webhook endpoint, and creation and update times.

> [tab] Credentials
>
> Artemis encrypts credentials after you save them. Leave a field blank to keep its current value.
>
> | Field | Description |
> | - | - |
> | **Use Auth Profile** | Authenticates outbound calls through a saved Auth Profile. |
> | **Genesys Auth Profile** | Selects or changes the bound Auth Profile. |
> | **Webhook Signature Secret** | Replace it here and in the Genesys integration together. |
>
> You can't edit the **Webhook Connection Token**, because the webhook URL embeds it. To replace it, create a new connection. Select **Save Credentials** to apply your changes.

> [tab] Configuration
>
> Update the connection's behavior.
>
> | Setting | Description |
> | - | - |
> | **Display Name** | The label operators see. |
> | **Provider Verification Strength** | How far the runtime trusts Genesys's identity assertion. |
> | **Integration ID** | The bound Open Messaging integration. |
> | **Activation Mode** | Switch from **Diagnostics only** to **Enabled** after validation. |
>
> Select **Save Changes** to apply your changes.

> [tab] Deployment
>
> Choose which deployed version answers messages.
>
> | Setting | Description |
> | - | - |
> | **Environment** | Under **Environment Binding**. Selects which deployed version handles incoming messages. |
> | **Active Deployment** | Shows the bound version and when someone deployed it, or a **Working Copy (draft)** warning. |
>
> Select **Save Changes** after you switch the environment.

> [tab] Testing
>
> The **Diagnostics** panel runs the checks in [Validate and enable](#validate-and-enable).
>
> | Control | Description |
> | - | - |
> | **Endpoint**, **Signature Secret** | The webhook under test and the secret that signs the test request. |
> | **Customer ID**, **Message**, **Originating Message ID** | The test conversation inputs. |
> | **Run Signature**, **Run Inbound**, **Run Receipt** | Run each diagnostic. |
> | **Last Success**, **Last Failure** | The most recent diagnostic outcomes. |
>
> The **Validation Evidence** panel records the results of those runs.
>
> | Group | Fields |
> | - | - |
> | Status | **Validated At**, **Status**, **Summary**, **Automated Provisioning Verified** |
> | Diagnostics | **Signature Diagnostic ID**, **Inbound Diagnostic ID**, **Receipt Diagnostic ID**, **Trace Count**, **Runtime Trace IDs** |
> | Conversation | **Delivery Mode**, **Provider Conversation ID**, **Sandbox Evidence References** |
> | Performance | **Max Concurrent Sessions**, **Chat Round Trip P95 ms**, **Packet Loss Percent** |
> | Operations | **Operator Runbook Reference**, **Operator Dashboard Reference**, **Operator Alert Reference** |

***

## Troubleshoot connection issues

Most failures trace to the signature, the activation mode, or the Auth Profile.

| Symptom | Likely cause | Recommended action |
| - | - | - |
| Connection not found | Generic path, lost token, or deleted connection | Use the full connection-specific URL through the correct project runtime, and confirm the connection still exists. |
| Webhook returns `401` | Signature mismatch | Confirm Genesys signs the exact raw body with the matching secret, in a supported header and format, and that the ingress proxy doesn't rewrite the body. |
| Diagnostics pass but Artemis ignores live messages | The adapter is still in diagnostics mode | Change **Activation Mode** to **Enabled**, and confirm the connection status is **Active**. |
| Inbound succeeds but replies fail | The Auth Profile can't reach the integration | Confirm the Auth Profile is active, uses connector `genesys`, targets the same region and organization, and can call the configured Integration ID. |
| Conversation context resets | The conversation ID changes | Make sure Genesys sends a stable conversation ID for follow-up turns, not a per-message identifier. |
| Text works but attachments don't | Default `metadata_only` media mode | Check media rejection reasons, allowed host suffixes, reference count, and payload size limits before you enable downloads. |

***

**Related articles:**

* [Channels](https://koreai.mintlify.site/agent-platform/channels.md)
* [Set up Genesys](https://koreai.mintlify.site/agent-platform/channels/genesys)
* [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.