Genesys Cloud

Overview

The Genesys Cloud integration sends the handovers of your AI Agent to the human agents of your Genesys Cloud organization. The customer stays on the channel of the conversation, such as the web channel or WhatsApp. The Genesys agent answers in Genesys Cloud, and Moveo sends each reply to the customer on that channel.

Genesys Cloud replaces Moveo live chat for an environment. Your AI Agent answers first, as on every other environment. When the AI Agent hands the conversation over, Moveo opens a conversation in Genesys Cloud through an Open Messaging integration.

note

You set up this integration with the Moveo API. The Moveo console does not show it on the Connections page.

---

Prerequisites

Before you set up the integration, make sure that you have the following.

✅ Genesys Cloud requirements

• A Genesys Cloud organization, and an administrator account that can create integrations, OAuth clients, roles and Architect flows.
• A queue with the human agents who take the handovers.

✅ Moveo requirements

• An AI Agent connected to an environment, and a rule that assigns the AI Agent to the conversations of the environment.
• A Handover action in the dialogs of the AI Agent.
• A Moveo API key of the Manage type. See API keys.

---

How it works

A conversation goes through Moveo and Genesys Cloud as follows:

1. A customer writes to your AI Agent on a channel of the environment. The AI Agent answers.
2. The AI Agent runs a Handover action. Moveo opens a conversation in your Open Messaging integration in Genesys Cloud.
3. The first message of the Genesys conversation contains the earlier messages of the conversation, so that the agent can read them.
4. Your Architect flow routes the conversation to a queue, and a Genesys agent accepts it.
5. Moveo sends the messages of the customer to the agent, and the replies of the agent to the customer.
6. When the agent ends the conversation in Genesys Cloud, Moveo resolves the conversation. A transfer to another agent or queue does not end it.

When the customer ends the conversation, or the Moveo session expires, Moveo ends the conversation in Genesys Cloud.

---

Setup guide

The setup goes back and forth between Genesys Cloud and the Moveo API.

Step 1: Create the OAuth client in Genesys Cloud

1. In Genesys Cloud, create a role with these permissions:

   Permission	What Moveo uses it for
   messaging:integration:view	Read the Open Messaging integration
   conversation:message:receive	Send the messages of the customer to Genesys Cloud
   analytics:conversationDetail:view	Detect the end of the conversation by the agent
   directory:user:view	Show the agent name and the profile photo of the agent. This is optional.

2. Give the role the divisions of the queues that take the handovers. Moveo needs these divisions to detect the end of a conversation by the agent.

3. Create an OAuth client with the Client Credentials grant, and assign the role to it.

4. Copy the client ID and the client secret.

Step 2: Create the Moveo integration

Create a genesys integration in your environment with the Add integration endpoint, POST /v1/desks/{desk_id}/integrations. The open_messaging_integration_id comes from Step 3, so you add it later.

curl -X POST "https://api.moveo.ai/api/v1/desks/<DESK_ID>/integrations?account_slug=<ACCOUNT_SLUG>" \
  -H "Authorization: apikey <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "genesys",
    "name": "Genesys Cloud",
    "active": true,
    "config": {
      "region": "eu-central-1",
      "oauth_client_id": "<CLIENT_ID>",
      "oauth_client_secret": "<CLIENT_SECRET>",
      "webhook_secret": "<WEBHOOK_SECRET>"
    }
  }'

• region is the AWS region of your Genesys Cloud organization. See Genesys Cloud regions.
• webhook_secret is a random string of your choice. Moveo uses it to verify the replies that Genesys Cloud sends. You enter the same value in Genesys Cloud in Step 3.

Keep the integration_id from the response. For an account in the United States or Brazil, use api.us-central.moveo.ai or api.sa-east.moveo.ai instead of api.moveo.ai.

Step 3: Create the Open Messaging integration in Genesys Cloud

1. In Genesys Cloud, go to Admin → Message → Platforms, and create an Open Messaging integration.

2. In the outbound notification webhook URL, enter the Moveo webhook URL of your region, with the integration_id from Step 2:

   Region	Webhook URL
   Europe	https://livechat.moveo.ai/v1/genesys/<INTEGRATION_ID>
   United States	https://livechat.us-central.moveo.ai/v1/genesys/<INTEGRATION_ID>
   Brazil	https://livechat.sa-east.moveo.ai/v1/genesys/<INTEGRATION_ID>

3. In the webhook signature secret token, enter the webhook_secret from Step 2.

4. To show typing indicators in both directions, turn on the typing events of the integration.

5. Save the integration, and copy its integration ID.

warning

Use the Moveo integration_id in the webhook URL, not the ID of the Open Messaging integration. Moveo rejects every reply of an integration without a webhook_secret, or with a secret that is different from the Genesys secret.

Step 4: Add the Open Messaging integration ID

Add the ID from Step 3 to the Moveo integration with the Update integration endpoint, PUT /v1/desks/{desk_id}/integrations/{integration_id}:

{
  "type": "genesys",
  "config": {
    "open_messaging_integration_id": "<OPEN_MESSAGING_INTEGRATION_ID>"
  }
}

Moveo merges the update with the stored configuration, so the other fields keep their values.

Step 5: Route the conversations with Architect

Create an inbound message flow in Architect, and set it as the message route of the Open Messaging integration. The flow must transfer the conversation to the queue of your agents.

Moveo adds these attributes to each Genesys conversation. Read them with Get Participant Data to choose a queue:

Attribute	Value
moveo_session_id	The Moveo session ID
moveo_desk_id	The environment ID
moveo_channel	The channel of the customer, such as web
moveo_integration_id	The integration that the customer writes to
moveo_account_slug	The Moveo account
moveo_brain_id	The AI Agent ID
moveo_is_test	true for a test conversation
moveo_tags	The tags, comma-separated
moveo_user_language	The language of the customer

Genesys Cloud limits the attributes of a conversation to 2048 bytes. When the tags do not fit, Moveo sends only the first tags.

Step 6: Select Genesys Cloud as the human chat of the environment

Set the integration as the human chat of the environment with the Update an environment endpoint, PUT /v1/desks/{desk_id}. In the same request, turn off Moveo live chat:

{
  "chat_integration_id": "<INTEGRATION_ID>",
  "is_service_desk": false
}

The integration must be active and verified. An environment cannot use Moveo live chat and Genesys Cloud at the same time.

---

Configuration options

Field	Required	Description
region	Yes	The AWS region of your Genesys Cloud organization, such as eu-central-1.
open_messaging_integration_id	Yes	The ID of the Open Messaging integration in Genesys Cloud.
oauth_client_id	Yes	The client ID of the OAuth client.
oauth_client_secret	Yes	The client secret of the OAuth client.
webhook_secret	Yes	The secret that signs the replies from Genesys Cloud.
agent_avatar	No	An https image URL of up to 4096 characters. It replaces the photo of every agent. null clears it.

Moveo hides oauth_client_secret and webhook_secret in the response to a read. To change a secret, send it in an update. Leave the secrets out of other updates.

Genesys Cloud regions

Use the AWS region code of your organization in region. Moveo accepts these codes:

• Americas: us-east-1, us-east-2, us-west-2, ca-central-1, sa-east-1
• Europe: eu-west-1, eu-west-2, eu-central-1, eu-central-2
• Asia Pacific: ap-south-1, ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-southeast-2
• Middle East: me-central-1

---

Messages

Agent identity

Each reply shows the name of the Genesys agent. When the agent has an agent name in Genesys Cloud, and the OAuth client has directory:user:view, the reply shows the agent name. A reply that Moveo cannot link to an agent, such as a welcome message of your Architect flow, shows Live Chat as the name.

The avatar of a reply is the agent_avatar of the integration. An integration without agent_avatar uses the profile photo of the agent in Genesys Cloud. An agent without a photo has no avatar.

Typing indicators

Moveo sends the typing of the customer to Genesys Cloud, and the typing of the agent to the customer. The customer sees the typing of the agent on channels that show typing indicators, such as the web channel. On WhatsApp, the customer does not see it.

Conversation history

The first message of the Genesys conversation holds the earlier messages of the conversation, up to 4096 bytes. In a long conversation, Moveo removes the oldest messages first. Files in the earlier messages show as (attachment).

End of the conversation

After the agent ends the conversation, Moveo resolves the conversation. On the web channel, the customer sees the conversation as resolved. If the survey is on, the customer can rate the conversation. The session stays open until it expires or the customer ends it. When the customer writes again before then, Moveo opens a new conversation in Genesys Cloud.

---

Testing your integration

1. Open a web conversation with your AI Agent, and trigger a dialog with a Handover action.
2. In Genesys Cloud, accept the conversation in the queue of your Architect flow. The first message shows the earlier messages.
3. Reply as the agent. The customer receives the reply with the agent name.
4. Type in the agent view. The webchat shows the typing indicator of the agent.
5. End the conversation in Genesys Cloud. The webchat shows the conversation as resolved.

---

Troubleshooting

The handover does not reach Genesys Cloud

• Make sure that the integration is active, and that chat_integration_id of the environment has the integration ID.
• Make sure that the integration has region, open_messaging_integration_id, oauth_client_id and oauth_client_secret, and that the region is in the list of regions.
• Make sure that the role of the OAuth client has conversation:message:receive.

The customer does not receive the replies of the agent

• Make sure that the webhook URL of the Open Messaging integration has the Moveo integration_id.
• Make sure that the webhook secret in Genesys Cloud and webhook_secret in Moveo are the same. When you change the secret, change it on both sides.

The conversation stays open after the agent ends it

The role of the OAuth client needs analytics:conversationDetail:view on the divisions of the queue. Add the missing divisions to the role. Messages in both directions work without this permission.

The customer receives a greeting from Live Chat

Your Architect flow sends a welcome message at the start of the conversation. Moveo sends all messages from Genesys Cloud to the customer. Change or remove the message in Architect.

The agent shows the full name instead of the agent name

Add directory:user:view to the role of the OAuth client. A changed agent name can take up to one hour to show.

---

Limitations

• You set up the integration with the Moveo API only.
• Agents answer handovers in Genesys Cloud. The environment does not use Moveo live chat.
• Genesys Cloud allows 400 API requests per minute for each OAuth client. Many conversations at the same time on one integration can reach this limit.
• The conversation history in Genesys Cloud is 4096 bytes at most, and earlier files show as (attachment).
• The attributes of a Genesys conversation are 2048 bytes at most.
• An agent reply with a file that has no https URL arrives without that file.

---

Resources

Moveo API

• Add integration
• Update integration
• Update an environment

Support

• Genesys Cloud resource center
• Moveo support: support@moveo.ai

---

Next steps

1. Write the dialogs that hand conversations over to your agents.
2. Add tags that your Architect flow uses to choose a queue.
3. Review the conversations in Analytics.