Set up Genesys Open Messaging

Back to 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:

Prepare Genesys Cloud and its authentication.
Artemis channel configuration: create the connection and copy its reveal-once values.
Webhook configuration in Genesys: set the signed webhook, or provision it from Artemis.
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.

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.

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.

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.

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.

Open Artemis and select the project.
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.

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.

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.

Select Create.
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.

Configure manually
Provision from Artemis

Paste the full connection-specific HTTPS URL into the Genesys Open Messaging integration. Keep the final connection token.
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.
Confirm Genesys signs the exact raw request body with HMAC-SHA256, in a supported header and format.

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.

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.
Run the inbound diagnostic. Confirm the adapter resolves the connection through the project runtime, normalizes the sender and conversation, and returns redacted provider metadata.
Run the receipt diagnostic. Confirm the Auth Profile obtains a token and calls the Genesys receipt endpoint for the configured Integration ID.
Change Activation Mode to Enabled, and confirm the connection status is Active.
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.

Credentials
Configuration
Deployment
Testing

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.

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.

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.

The Diagnostics panel runs the checks in 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:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Set up Genesys Open Messaging

Prerequisites

Prepare Genesys Cloud

Artemis channel configuration

Webhook configuration in Genesys

Validate and enable

Messaging and delivery behavior

Security and operational boundaries

Manage the channel connection

Troubleshoot connection issues

​Prerequisites

​Prepare Genesys Cloud

​Artemis channel configuration

​Webhook configuration in Genesys

​Validate and enable

​Messaging and delivery behavior

​Security and operational boundaries

​Manage the channel connection

​Troubleshoot connection issues

Prerequisites

Prepare Genesys Cloud

Artemis channel configuration

Webhook configuration in Genesys

Validate and enable

Messaging and delivery behavior

Security and operational boundaries

Manage the channel connection

Troubleshoot connection issues