> This page is for API Reference & Tools.

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

# Live Agent Integrations

> Create, read and update Live Agent Integrations through the Moveworks Configuration API: endpoints, fields and examples.

`tool.live-agent.integrations`

One per live-agent channel; `name` (lowercase snake_case) is the join key from handoff items.

* **Endpoint:** `/tool/live-agent/integrations`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch. Send only the fields you change, plus `version: {num, change_description}` with the `num` from your last read. Lists and maps you send replace the stored ones whole.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                 | Endpoint reference                                                                                                                         |
| ------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET`   | `/tool/live-agent/integrations`      | [List live agent integrations](/api-reference/configuration-api/handoff-live-agent/live-agent-integrations/list-live-agent-integrations)   |
| `POST`  | `/tool/live-agent/integrations`      | [Create live agent integration](/api-reference/configuration-api/handoff-live-agent/live-agent-integrations/create-live-agent-integration) |
| `GET`   | `/tool/live-agent/integrations/{id}` | [Get live agent integration](/api-reference/configuration-api/handoff-live-agent/live-agent-integrations/get-live-agent-integration)       |
| `PATCH` | `/tool/live-agent/integrations/{id}` | [Update live agent integration](/api-reference/configuration-api/handoff-live-agent/live-agent-integrations/update-live-agent-integration) |

### Fields

| Field                   | Type                     | Required  | Notes                                                                                                                                                                      |
| ----------------------- | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string                   | read-only | Unique identifier of the handoff configuration, assigned by the server.                                                                                                    |
| `name`                  | string                   |           | Unique key used to refer to this handoff. Must start with a lowercase letter and contain only lowercase letters, digits and underscores. Cannot be changed after creation. |
| `channel`               | ChannelHandoffConfig     |           | Hands off by routing the user's messages to a channel where agents respond.                                                                                                |
| `api`                   | ApiHandoffConfig         |           | Hands off through a live agent provider's API, such as Vayusphere or BeyondTrust.                                                                                          |
| `url`                   | UrlHandoffConfig         |           | Hands off by directing the user to a URL that connects them to an agent.                                                                                                   |
| `agent_broker`          | AgentBrokerHandoffConfig |           | Hands off by brokering the chat to a live agent provider, such as Amazon Connect, ServiceNow, Genesys or Salesforce.                                                       |
| `file_ticket_enabled`   | boolean                  |           | If true, a ticket is automatically filed for the user whenever they request a live agent.                                                                                  |
| `ticket_receipt_traits` | AgentHandoffTicketTraits |           | Additional settings for the ticket filed when a user requests a live agent.                                                                                                |
| `updated_time`          | string                   | read-only | When the configuration was last updated.                                                                                                                                   |
| `updated_by`            | string                   | read-only | Who last updated the configuration.                                                                                                                                        |
| `version`               | Version                  | ✅         | Document version. On update, send back the num from your last read.                                                                                                        |

Set at most one of `channel`, `api`, `url`, `agent_broker`.

### Variants (4, pick one)

**`channel`**

Hands off by routing the user's messages to a channel where agents respond.

| Field    | Type                       | Required | Notes                                                                   |
| -------- | -------------------------- | -------- | ----------------------------------------------------------------------- |
| `routes` | array\<ChannelRouteConfig> | ✅        | Channels the user's messages can be routed to. Between 1 and 20 routes. |

**`api`**

Hands off through a live agent provider's API, such as Vayusphere or BeyondTrust.

| Field          | Type                                | Required | Notes                                                          |
| -------------- | ----------------------------------- | -------- | -------------------------------------------------------------- |
| `vayusphere`   | VayusphereLiveAgentApiHandoffConfig |          | Hands off to a live agent queue through the Vayusphere API.    |
| `beyond_trust` | BeyondTrustApiHandoffConfig         |          | Hands off to a live agent session through the BeyondTrust API. |

In `api`, set at most one of `vayusphere`, `beyond_trust`.

**`url`**

Hands off by directing the user to a URL that connects them to an agent.

| Field                             | Type    | Required | Notes                                                                                                                                                  |
| --------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `base_url`                        | string  |          | Base URL that connects the user to an agent. Must start with http\:// or https\:// when set.                                                           |
| `user_comment_collection_enabled` | boolean |          | If true, a comment is collected from the user and made available to the URL parameter mapper under the key 'user_text'.                                |
| `url_params_bender`               | object  |          | Data mapper that defines the URL parameters Moveworks adds to the handoff URL.                                                                         |
| `url_tracking_enabled`            | boolean |          | If true, the URL is wrapped as a Moveworks link so clicks are tracked in analytics. Not recommended for Microsoft Teams, where it opens a browser tab. |

**`agent_broker`**

Hands off by brokering the chat to a live agent provider, such as Amazon Connect, ServiceNow, Genesys or Salesforce.

| Field                      | Type                       | Required | Notes                                                                                                                              |
| -------------------------- | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `anonymous_agents_enabled` | boolean                    |          | If true, the live agent provider uses anonymous agents.                                                                            |
| `amazon_connect`           | AmazonConnectHandoffConfig |          | Settings for brokering live agent chats to Amazon Connect.                                                                         |
| `eight_x_eight`            | EightXEightHandoffConfig   |          | Settings for brokering live agent chats to 8x8.                                                                                    |
| `snow`                     | SnowHandoffConfig          |          | Settings for brokering live agent chats to ServiceNow.                                                                             |
| `glia`                     | GliaHandoffConfig          |          | Settings for brokering live agent chats to Glia.                                                                                   |
| `fresh_chat`               | FreshChatHandoffConfig     |          | Settings for brokering live agent chats to Freshchat.                                                                              |
| `five_nine`                | FiveNineHandoffConfig      |          | Settings for brokering live agent chats to Five9.                                                                                  |
| `genesys`                  | GenesysHandoffConfig       |          | Settings for brokering live agent chats to Genesys.                                                                                |
| `salesforce`               | SalesforceHandoffConfig    |          | Settings for brokering live agent chats to Salesforce.                                                                             |
| `session_timeout_seconds`  | integer                    |          | Seconds of inactivity after which a live agent session is automatically ended. Defaults to 120 seconds if not set.                 |
| `connector_id`             | string                     |          | Connector used to start the live agent connection. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors). |

In `agent_broker`, set at most one of `amazon_connect`, `eight_x_eight`, `snow`, `glia`, `fresh_chat`, `five_nine`, `genesys`, `salesforce`.

### Example create body

```json
{
  "name": "example",
  "file_ticket_enabled": true,
  "channel": {
    "routes": [
      {
        "channel_id": "<id>",
        "connector_id": "<connector-uuid>"
      }
    ]
  },
  "version": {
    "change_description": "Create live agent integration"
  }
}
```