Set up Genesys

Back to messaging or digital channels Connect your agent to Genesys Cloud as a Bot Connector so an Architect message flow can hand a conversation to it for intent and slot processing. You install the Bot Connector integration in Genesys, bind its Stream ID and shared secret to Artemis, then call the integration from an Architect flow. This channel works differently from every other messaging channel. Genesys sends one authenticated POST carrying the user’s turn and holds that request open while your agent runs, then reads the reply out of the same HTTP response. There’s no callback and no later send API. The setup requires:

Genesys Cloud setup: install and name the Bot Connector integration, and note its Stream ID.
Artemis channel configuration using the Stream ID and a shared secret you generate, then copy the generated Bot Connector URL.
Bot Connector configuration in Genesys: set that URL and the same secret on the integration, activate it, and call it from an Architect flow.

After you complete the configuration, an Architect flow reaching the Call Bot Connector action sends the turn to Artemis, the bound deployment answers inside the same request, and Architect branches on the intent your agent returns. Important considerations

The response travels in the same request: Genesys waits for your agent. Provider timeout and agent execution time have to be compatible, and this channel stays non-streaming by design.
Client Secret isn’t a Genesys OAuth secret: for Bot Connector, it’s a pre-shared bearer token you invent and configure identically on both sides. Substituting an OAuth integration secret fails unless Genesys sends that same value on the webhook request.
Bot Connector needs a subscription change: Genesys requires you to contact Genesys Cloud Sales before you can install the integration.
Architect intents must already exist: Artemis returns intent names that Genesys matches to branches in your flow. It doesn’t create or validate them, so a name that doesn’t exist in Architect produces a branch that never fires.

Prerequisites

A Genesys Cloud organization with the Bot Connector integration available on your subscription, in the region that owns the Architect flow.
Admin access in Genesys Cloud, with permission to install integrations and edit Architect flows.
An Architect message flow where the conversation should reach the agent, or permission to create one.
Artemis project access with permission to open Deployments -> Channels, and a deployed agent in the environment you intend to bind.

How Artemis handles Bot Connector requests

Genesys posts to a URL ending in the Stream ID, so Artemis resolves the connection from that path segment and the conversation from the payload.

Piece	Who owns it	What it does
Stream ID	Genesys	Routes inbound requests. Artemis reads the final path segment and matches it to an active connection. It’s a routing identifier rather than a secret.
Client Secret	You	Authenticates the request. Artemis compares the token Genesys sends with the stored secret using a timing-safe check.
Genesys conversation ID	Genesys	Identifies each end-user session inside the connection. Artemis keys the session to it, so 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, and the generic Genesys route alone can’t select a connection.

Because the exchange is synchronous, the HTTP response carries everything Genesys needs: the reply messages, the bot state, the intent, and whether the task ended. Nothing arrives later.

Genesys Cloud setup

Do this work in Genesys Cloud before you open Artemis. Genesys documents the same screens in Configure the Genesys Bot Connector integration.

Sign in to the Genesys Cloud organization and regional domain that own the Architect flow you intend to change.Genesys organizations are region-specific, so a development organization’s integration pointed at production Artemis produces a setup that looks correct but serves the wrong traffic. Confirm the organization before you install anything.

Install the Bot Connector integration

Select Admin, then under Integrations, select Integrations. On newer navigation, select Menu -> IT and Integrations -> Integrations.
Search for the Genesys Bot Connector tile and click Install.
On the Details tab, give the integration a name that identifies the agent and the environment, and add notes if your team uses them.

Pick a distinct name. Architect actions reference integrations by name, so duplicates make it easy to point a flow at the wrong one later.Don’t install the Genesys Digital Bot Connector tile by mistake. It’s a separate integration with its own Architect action, and Artemis connects through Bot Connector. Keep this integration’s lifecycle separate from Open Messaging and Audio Connector integrations too.Genesys allows up to five Bot Connector integrations per organization, which is the practical ceiling on how many Artemis connections one organization can carry.

Copy the Stream ID

Copy the Stream ID Genesys shows for this integration, exactly as it appears.This becomes the routing identifier in Artemis and the last segment of the webhook URL. Copy it without surrounding whitespace, because a trailing space produces a 404 that looks like a missing connection.Don’t substitute the Genesys organization ID, the integration ID, an OAuth client ID, a conversation ID, or the Architect flow ID. None of them route.

Generate a Client Secret

Create a high-entropy random string. You invent this value rather than Genesys issuing it, and you’ll enter the identical string in two places: the Artemis connection, and the Bot Connector credentials in Genesys.Use a different secret per environment, and store it in your secret manager. This token is the only thing standing between the public URL and your agent.

Artemis channel configuration

Create the connection before you configure the integration in Genesys. Artemis resolves the Stream ID and decrypts the secret before it authenticates a request, so an inactive or missing connection returns 404 even when the URL is right.

Open Artemis and select the project.
Go to Deployments -> Channels -> Genesys -> + New.

Configure the following fields:

Artemis connection field	Source / Notes
Display Name	The label operators see in the connections list. Name it for the Genesys organization and the environment it serves, because a project can hold several Genesys connections. Routing ignores this value.
Stream ID	The routing key. Artemis writes it into the webhook path and resolves the connection from it. Enter the exact value from the Bot Connector integration, with no leading or trailing whitespace.
Client Secret	The shared bearer token you generated. Artemis compares the token on each request with this encrypted value using a timing-safe check.
Environment	The published environment whose active deployment answers the Architect flow. Leave the working copy default only while you develop.
Provider Verification Strength	How far Artemis trusts Genesys’s identity assertion when it links a caller to an existing session. Weak suits most deployments. Choose Strong only when you trust those assertions enough to base continuity and account-linking decisions on them.
Initial Status	Whether the connection handles requests. Set it to Active, because an inactive connection returns 404 rather than an authentication error, which sends you looking in the wrong place.

Click Create.
Open the connection and copy the Webhook URL from the Overview tab.
The URL ends with the URL-encoded Stream ID. Copy the whole thing, because the generic Genesys route can’t identify which connection a request belongs to.

Validation checklist

Validation item	Expected result
Confirm the subscription	The Genesys Bot Connector tile appears in your organization’s integration list.
Install the integration	Bot Connector integration installed and named distinctly, in the region that owns the flow.
Copy the Stream ID	Stream ID copied exactly, with no surrounding whitespace, and distinct from organization, integration, and flow IDs.
Create the Artemis connection	Connection saved as Active with the Stream ID and the shared secret.
Copy the webhook URL	Bot Connector URL copied from the Overview tab, ending with the encoded Stream ID.
Configure the integration	URL and matching secret saved on the integration, and its status set to active.
Map the Architect outcomes	Intent names in Artemis match branches that already exist in the Architect flow.
Wire the Architect action	Call Bot Connector action added to the flow, pointing at this integration, with its failure path connected.
Run a test interaction	Test turn reaches the agent and Architect branches on the returned intent. See Verify the connection.

Bot Connector configuration in Genesys

Return to the integration you installed and finish it with the URL and secret from Artemis, then call it from a flow.

Set the Bot Connector URL

Open the integration’s Configuration tab and set the Bot Connector URL to the Webhook URL from the Artemis connection.Preserve the encoded Stream ID at the end. Genesys uses this URL to relay each utterance, so a truncated path reaches Artemis and resolves to nothing.

Add the shared secret as credentials

Open the integration’s Credentials tab and configure the same Client Secret you entered in Artemis as the bearer token.Artemis prefers the token on an Authorization: Bearer header. It also accepts x-channel-secret, x-ingress-secret, or x-webhook-secret. It never accepts a token in the query string, so don’t append one to the URL.

Activate the integration

Set the integration status to active.An inactive integration doesn’t appear in Architect at all, so this step has to come before you try to add the action.

Add the Call Bot Connector action to a flow

Open the Architect message flow that should reach the agent.
From the toolbox, drag a Call Bot Connector action into the flow.
Set the action’s bot integration to the integration you just configured, and set the name and version fields the action asks for.
Connect the action’s failure path to real handling rather than leaving it unconnected.

Genesys documents the action’s inputs, timeouts, and error types in Call Bot Connector action. The failure path matters: Architect takes it on execution errors and connectivity problems, and it also takes a safety path after four consecutive turns return an unchanged intent.

Validate before you publish

Run Architect’s validation and test the flow on a non-production interaction.Publish only after you’ve confirmed the URL, the secret, the response timing, and the failure branches. A published flow with an unreachable bot fails in front of customers.

Map Architect outcomes

Artemis returns an intent name to Genesys at the end of each turn, and Architect branches on it. Configure the mapping on the connection’s Configuration tab, under Architect outcome mapping. Turn on Enable terminal intent mapping, then set the intent name Artemis returns for each outcome.

Outcome	Artemis returns it when
Continue conversation	The conversation should stay with this agent for another turn.
Escalate to an agent	The conversation should transfer to a human.
Close the session	The conversation should end.

Each outcome takes a Value source of either a literal intent name you type, or a project variable that supplies it. Use a project variable when the same agent serves several Genesys flows with different intent vocabularies, and a literal name otherwise. These names have to match intents and branches that already exist in your Architect flow. Artemis neither creates nor validates them, so a typo produces a branch Architect never takes rather than an error you can see. Agree the names with whoever owns the flow before you enter them here.

Verify the connection

Test each failure mode as well as the happy path, because Architect’s branching depends on Artemis returning the right status for each one.

Send a text turn with a unique message and a stable Genesys conversation ID.
Confirm an HTTP 200 and one text reply in the response.
Send a second turn reusing the same conversation ID, and confirm it resumes the same session.
A different conversation ID should open a separate session.
Return an authored quick reply, send its encoded payload back as the button response, and confirm the session resumes with the action value you authored.
Send a request with the wrong secret and confirm it returns 401.
Send a request to an unknown or inactive Stream ID and confirm it returns 404.
Send malformed input and confirm it returns 400.
Confirm the Architect flow handles a 503 busy response and an execution failure without looping.

Request and response contract

Genesys carries the whole turn in one exchange, so both halves have required fields.

Direction	Required content
Request	A non-empty Genesys conversation ID and an input message type. A text turn also needs the message text; a structured quick reply needs the button response payload.
Response	The reply messages, the bot state, the intent name, and whether the task ended. Genesys reads all of these from the same HTTP response.

Keep the conversation ID stable across every turn in one Genesys interaction. Replacing it with the Stream ID or an ephemeral request ID resets the conversation context, which looks like the agent forgetting rather than like a configuration error. Optional session metadata crosses a trust boundary, so Artemis validates it before the agent runs. Send it only in the JSON object shape Artemis expects.

Secure the connection

The Stream ID appears in a public URL and isn’t a secret. HTTPS and the shared token protect the endpoint, so never put the token in the URL or in logs. Use a unique, high-entropy Client Secret for each environment, stored only in the Genesys integration’s secure credential configuration and in encrypted Artemis credentials. Rotating it means changing both sides together, because Artemis rejects a request the moment the values diverge. Prefer the Authorization: Bearer header. If your ingress adds or rewrites headers, make sure it preserves the one Genesys sends and strips any untrusted duplicate before the request reaches Artemis. Two competing authorization headers produce a 401 that looks like a wrong secret. Use separate Genesys integrations, Stream IDs, secrets, Architect flows or versions, and connections for development and production.

Manage the channel connection

Opening a connection shows four tabs. The delete control sits beside the connection name.

Overview
Credentials
Configuration
Deployment

Connection Summary reports the connection’s state and identity.

Field	Description
Status	Whether the connection currently handles requests.
Created and Updated	Date and time of creation, and of the last change.
Environment	The environment whose deployment answers requests.
Source Type	Reads `Channel Connection`.
Source ID	Identifies the connection uniquely. Quote it when you raise a support ticket.

Setup Instructions shows the Webhook URL to configure in Genesys and the Stream ID it ends with, each with a copy control. Compare the Stream ID here with the integration’s whenever requests return 404.

Artemis encrypts the secret after you save it, so the field reads as saved rather than showing its value. Leave it empty to keep the current value, or enter a new one to replace it.

Field	Description
Use Auth Profile	Draws the credential from a saved auth profile instead of the field below. Prefer it when the same secret serves more than one connection, since a rotation then touches one profile.
Client Secret	The shared bearer token. Change it here and in the Genesys integration as one coordinated step, because the two have to match on every request.

Click Save Credentials to apply your changes.

Under General, rename the connection with Display Name, and revisit Provider Verification Strength if your trust posture for this organization changes.Under Genesys Settings, Stream ID appears read-only. The webhook URL is built from it, so changing it would invalidate the URL configured in Genesys. Create a new connection to serve a different integration.Authorization Message controls what the customer sees when a tool needs them to authorize something before the conversation continues. Write the template with these variables.

Scope	Variables	Use
Message	`{{total}}`, `{{completed}}`, `{{remaining}}`	Summarize progress across every pending authorization, typically in a lead-in line above the list.
Repeat block	`{{#authorizations}}` and `{{/authorizations}}`	Wrap the section Artemis repeats once per pending authorization.
Item	`{{profileName}}`, `{{authLink}}`, `{{authUrl}}`, `{{index}}`, `{{count}}`	Identify and link each authorization inside the repeat block.

Architect outcome mapping sets the intent names Artemis returns to Genesys. See Map Architect outcomes.Click Save Changes to apply your changes.

Troubleshoot connection issues

Symptom	Likely cause	Recommended action
The webhook returns 404	The Stream ID doesn’t match, or the connection isn’t active	Confirm the URL ends with the exact Stream ID, check the saved identifier for copied whitespace, and confirm the connection is Active in the intended project.
The webhook returns 401	The token doesn’t match, or headers conflict	Send the exact Client Secret through `Authorization: Bearer` or a supported secret header, remove duplicate authorization headers at your ingress, and confirm nobody rotated the secret on one side only.
The webhook returns 400	The request is missing a required field	Include a non-empty conversation ID and an input message type. Text turns also need the message text, and structured actions need the button response payload.
The webhook returns 503 busy	Concurrent turns for the same session couldn’t acquire the lock	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 configured timeout with actual execution duration, investigate model and tool latency, and keep this channel synchronous and non-streaming.
Text works but quick replies don’t	The response lacks structured entries, or the payload doesn’t return	Confirm the response carries quick reply entries and that the selected encoded payload comes back as the button response payload.
Conversation context resets between turns	The conversation ID changes each turn	Preserve the same Genesys conversation ID for every turn in one interaction, and don’t replace it with the Stream ID or a per-request identifier.
Architect never takes the expected branch	The intent name doesn’t exist in the flow	Compare the names in Architect outcome mapping with the intents and branches in Architect. Artemis doesn’t create or validate them.
The integration doesn’t appear in Architect	The integration isn’t active	Set the integration’s status to active in Genesys Cloud, then reopen the flow.

Genesys reference

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

Resource	Use it for
About Genesys Bot Connector	What the connector supports, including quick replies, cards, and carousels.
Configure the Genesys Bot Connector integration	Installing the integration, its tabs, and activating it.
Call Bot Connector action	Action inputs, response timeouts, session variables, error types, and failure paths.
About Genesys Digital Bot Connector	Telling the two connectors apart, if you’re unsure which one your flow uses.

Related articles:

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Prerequisites

How Artemis handles Bot Connector requests

Genesys Cloud setup

Artemis channel configuration

Validation checklist

Bot Connector configuration in Genesys

Map Architect outcomes

Verify the connection

Request and response contract

Secure the connection

Manage the channel connection

Troubleshoot connection issues

Genesys reference

​Prerequisites

​How Artemis handles Bot Connector requests

​Genesys Cloud setup

​Artemis channel configuration

​Validation checklist

​Bot Connector configuration in Genesys

​Map Architect outcomes

​Verify the connection

​Request and response contract

​Secure the connection

​Manage the channel connection

​Troubleshoot connection issues

​Genesys reference

Prerequisites

How Artemis handles Bot Connector requests

Genesys Cloud setup

Artemis channel configuration

Validation checklist

Bot Connector configuration in Genesys

Map Architect outcomes

Verify the connection

Request and response contract

Secure the connection

Manage the channel connection

Troubleshoot connection issues

Genesys reference