Set up Genesys

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

Genesys Cloud setup: install the Bot Connector integration and copy its Stream ID.
Artemis channel configuration: create the connection, then copy its Webhook URL.
Bot Connector configuration in Genesys: set the URL and secret, activate the integration, and call it from Architect.
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.

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

Install the Bot Connector integration

Go to Admin -> Integrations -> Integrations. On newer navigation, go to Menu -> IT and Integrations -> Integrations.
Find the Genesys Bot Connector tile and select Install.
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.

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.

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.

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

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.

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

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.

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.

Activate the integration

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

Add the Call Bot Connector action

Open the Architect flow that should reach the agent.
Add or select a Call Bot Connector action, and point it at this integration.
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.

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.

Turn on Enable terminal intent mapping.
For each outcome, select a Value source and enter the Genesys Architect intent name.
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.

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.

Send inputMessage.type=Text with a unique message and a stable genesysConversationId. Confirm HTTP 200 and one Text reply in replymessages.
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.
Return an authored button, send its encoded payload in inputMessage.buttonResponse.payload, and confirm the session resumes with the right action value.
Confirm a wrong secret returns 401, an unknown or inactive Stream ID returns 404, and malformed input returns 400.
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.

Credentials
Configuration
Deployment

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.

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.

Select Save Changes to apply your changes.

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	What the connector supports.
Configure the Genesys Bot Connector integration	Installing and activating the integration.
Call Bot Connector action	Action inputs, timeouts, error types, and failure paths.
About Genesys Digital Bot Connector	Telling the two connectors apart.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prerequisites

How Artemis routes Bot Connector requests

Genesys Cloud setup

Artemis channel configuration

Bot Connector configuration in Genesys

Validation checklist

Map Architect outcomes

Verify the connection

Request and response contract

Security and operational boundaries

Manage the channel connection

Troubleshoot connection issues

Genesys reference

​Prerequisites

​How Artemis routes Bot Connector requests

​Genesys Cloud setup

​Artemis channel configuration

​Bot Connector configuration in Genesys

​Validation checklist

​Map Architect outcomes

​Verify the connection

​Request and response contract

​Security and operational boundaries

​Manage the channel connection

​Troubleshoot connection issues

​Genesys reference

Prerequisites

How Artemis routes Bot Connector requests

Genesys Cloud setup

Artemis channel configuration

Bot Connector configuration in Genesys

Validation checklist

Map Architect outcomes

Verify the connection

Request and response contract

Security and operational boundaries

Manage the channel connection

Troubleshoot connection issues

Genesys reference