> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/docs/handoffs/genesys/configure-the-handoff/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Configure the handoff

After you complete the [initial configuration](/docs/handoffs/genesys/initial-configuration) and share your credentials, your Ada team sets up the backend integration. When that is complete, the Genesys block becomes available in your AI Agent and you can configure the handoff. In Genesys, each handoff creates a new Open Messaging conversation routed by your Inbound Message flow, and Ada bidirectionally relays text messages and attachments between the end user and the human agent.

> **Info**
>
> Your Ada team will complete the backend integration setup, including connecting the Genesys app and making the Genesys block available in your AI Agent. Contact your Ada representative to confirm this step is finished before proceeding.

## Add the Genesys block

Each handoff uses the Genesys block to escalate the conversation to a human agent in Genesys.

**To add the Genesys block:**

1. In your Handoff answer, add the **Genesys** block with the action **Handoff to a human agent**.
2. Confirm the two required Ada ID fields are pre-populated by the block:
   * `ada_conversation_id` → `@oauth/conversation_id`
   * `ada_user_id` → `@oauth/end_user_id`
3. Map AI Agent variables into any of the optional fields described below.

> **Note**
>
> Select the action labeled **Handoff to a human agent**, not **Handoff to a human agent (legacy)**. The legacy action runs a deprecated handoff and will be removed in a future update.

## Handoff input fields

The Genesys block accepts the following input fields. Only the two Ada ID fields are required; all others are optional.

| Field                 | Required | Description                                                                                                                                                                                                                       |
| --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ada_conversation_id` | Yes      | Ada conversation ID. Populated by `@oauth/conversation_id`.                                                                                                                                                                       |
| `ada_user_id`         | Yes      | Ada end user ID. Populated by `@oauth/end_user_id`.                                                                                                                                                                               |
| `first_name`          | No       | End user first name. Sent on the Open Messaging sender — accessible in the Architect flow via `Message.Message.senderAddressInfo.name`.                                                                                           |
| `last_name`           | No       | End user last name. Combined with `first_name` for the Open Messaging sender name.                                                                                                                                                |
| `email_address`       | No       | End user email. Attached to the Open Messaging sender — accessible in the Architect flow via `Message.Message.senderAddressInfo.email`.                                                                                           |
| `custom_attributes`   | No       | JSON object of additional custom attributes (for example, `{"key1": "value1"}`). Forwarded to Genesys as `channel.metadata.customAttributes` and retrievable in the Inbound Message flow via the **Get Participant Data** action. |
| `transcript_summary`  | No       | Summary text appended after the conversation transcript at handoff.                                                                                                                                                               |
| `agent_name_override` | No       | Static display name shown in Ada for all agent messages — overrides the name fetched from the Genesys user. Useful when you want a generic "Agent" or "Support" label.                                                            |

To expose specific custom-attribute fields as named inputs on the block instead of using the catch-all `custom_attributes` field, see [Custom fields](/docs/handoffs/genesys/custom-fields).

## Test the handoff

It is recommended to test the handoff end-to-end after your Ada team confirms the install is complete and you have associated the Open Messaging integration with your Inbound Message flow.

**To test the handoff:**

1. In Genesys, confirm the Open Messaging integration is associated with an Inbound Message flow under **Admin → Orchestration → Routing → Message Routing**. Without this association, no handoffs route to a queue.
2. Trigger a test handoff from the AI Agent — for example, through a sandbox conversation that escalates to the handoff answer.
3. In Genesys, confirm a new Open Messaging conversation appears in an agent's queue.
4. As the agent, accept the conversation and send a reply.
   The message appears in the Ada conversation.
5. End the conversation in Genesys by wrapping it up.
   The Ada conversation resumes, allowing the end user to continue chatting with the AI Agent.

## Frequently asked questions

Common questions about configuring the Genesys handoff are answered below.

### How are end-user details such as name and email passed through?

`first_name`, `last_name`, and `email_address` are sent on the Open Messaging sender record. Inside the Architect Inbound Message flow they are available as the built-in variables `Message.Message.senderAddressInfo.name` and `Message.Message.senderAddressInfo.email`.

### How can custom attributes be passed from the conversation to Genesys?

Use the `custom_attributes` input on the block (a JSON object), or define custom fields to expose them as named inputs on the block. Both routes end up as `channel.metadata.customAttributes` on the Genesys conversation and can be read in the Architect flow via the **Get Participant Data** action. See [Custom fields](/docs/handoffs/genesys/custom-fields) for details.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).