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

# Surfaces

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

`assistant.surfaces`

* **Endpoint:** `/assistant/surfaces`  |  **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`   | `/assistant/surfaces`      | [List surfaces](/api-reference/configuration-api/platform-org/surfaces/list-surfaces)   |
| `POST`  | `/assistant/surfaces`      | [Create surface](/api-reference/configuration-api/platform-org/surfaces/create-surface) |
| `GET`   | `/assistant/surfaces/{id}` | [Get surface](/api-reference/configuration-api/platform-org/surfaces/get-surface)       |
| `PATCH` | `/assistant/surfaces/{id}` | [Update surface](/api-reference/configuration-api/platform-org/surfaces/update-surface) |

### Fields

| Field                     | Type    | Required  | Notes                                                                                                                                                                                                                                                                 |
| ------------------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                      | string  | read-only | Unique ID of this configuration, assigned by the server.                                                                                                                                                                                                              |
| `assistant_id`            | string  |           | Bot ID of the account the assistant sends messages from, e.g. the Slack bot ID starting with B or the Google Chat bot email. For web chat it is generated from name and can be left empty on create.                                                                  |
| `name`                    | string  |           | Unique Moveworks identifier for the bot, in the form orgname-channel (e.g. acme-slack). Letters, digits, underscores and hyphens only. Cannot be changed after creation.                                                                                              |
| `assistant_name`          | string  |           | Customer-facing display name of the bot, usually the same across all of an organization's bots.                                                                                                                                                                       |
| `channel`                 | enum    | ✅         | Chat platform this bot runs on. Allowed values: msteams, movewebchat, slack, gchat, webex, zoom, glip, sms, conversationsrestapi. Cannot be changed after creation. One of: `msteams`, `movewebchat`, `slack`, `gchat`, `webex`, `zoom`, `glip`, `sms`, … (9 values). |
| `connector_id`            | string  |           | Connector used for this chat integration. Required except for movewebchat, gchat, zoom and webex, where one is created automatically if left empty. Cannot be changed after creation. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors). |
| `file_attachment_enabled` | boolean |           | If true, users can send file attachments to the bot.                                                                                                                                                                                                                  |
| `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 `ms_teams_config`, `slack_config`, `movewebchat_config`, `gchat_config`, `webex_config`, `zoom_config`, `glip_config`, `sms_config`, `conversations_rest_api_config`.

### Variants (9, pick one)

**`ms_teams_config`**

Microsoft Teams settings. Set this when channel is msteams.

| Field                                       | Type                                | Required | Notes                                                                                                                                                                                                              |
| ------------------------------------------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `app_id`                                    | string                              |          | Microsoft Teams app ID, as a lowercase GUID.                                                                                                                                                                       |
| `app_guid`                                  | string                              |          | Microsoft Teams app GUID, as shown in the Teams client. Needed when the bot was installed with the Teams app registration method.                                                                                  |
| `tenant_id`                                 | string                              |          | Microsoft Teams (Entra) tenant ID, as a lowercase GUID.                                                                                                                                                            |
| `msteams_app_store_credentials`             | MSTeamsAppStoreCredentials          |          | Use no credentials because the Moveworks app was installed from the Microsoft Teams Store (AppSource). Supports only one Teams bot per customer. Set this, credentials_secret or oauth2_jwt_client_assertion_auth. |
| `credentials_secret`                        | string                              |          | Microsoft Graph client secret generated in the Azure portal for your Azure Bot app. Set this, msteams_app_store_credentials or oauth2_jwt_client_assertion_auth. Secret: always returned masked as \*\*\*\*\*.     |
| `oauth2_jwt_client_assertion_auth`          | MSTeamsOauth2JwtClientAssertionAuth |          | Certificate-based authentication using OAuth2 client credentials with a JWT assertion. Set this, msteams_app_store_credentials or credentials_secret.                                                              |
| `region`                                    | enum                                |          | Microsoft Teams region, set only if the app lives in a regional Microsoft tenant. Allowed values: AMER, APAC, EMEA, GCC, GCCH, or empty. One of: \`\`, `AMER`, `APAC`, `EMEA`, `GCC`, `GCCH`.                      |
| `teams_single_tenant_auth_endpoint_enabled` | boolean                             |          | If true, the bot uses single-tenant Microsoft authentication. Needed for new non-App Store Teams bots created after July 2025.                                                                                     |

In `ms_teams_config`, set at most one of `msteams_app_store_credentials`, `credentials_secret`, `oauth2_jwt_client_assertion_auth`.

**`slack_config`**

Slack settings. Set this when channel is slack.

| Field                    | Type    | Required | Notes                                                                                                                   |
| ------------------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `app_id`                 | string  |          | Slack app ID, starting with A.                                                                                          |
| `user_id`                | string  |          | Slack user ID of the bot, starting with U or W.                                                                         |
| `team_id`                | string  |          | Slack team (workspace) or enterprise ID, starting with T or E.                                                          |
| `assistant_id`           | string  |          | Slack bot ID, starting with B.                                                                                          |
| `chat_system_url`        | string  |          | URL of your Slack workspace, e.g. [https://acme.slack.com](https://acme.slack.com).                                     |
| `instance_name`          | string  |          | Name of your Slack instance.                                                                                            |
| `signing_secret`         | string  |          | Slack signing secret used to verify requests sent by Slack. Secret: always returned masked as \*\*\*\*\*.               |
| `region`                 | string  |          | Slack cloud hosting the app. Allowed values: COMMERCIAL, GOV. Use GOV only if the Slack app is hosted in the GOV cloud. |
| `allow_multiple_threads` | boolean |          | If true, the bot can handle multiple concurrent chat threads. Enable this when using Slack agent mode.                  |

**`movewebchat_config`**

Moveworks web chat settings. Set this when channel is movewebchat.

| Field              | Type   | Required | Notes                                                                                                      |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `on_prem_agent_id` | string |          | ID of the on-premises agent used by this web chat bot.                                                     |
| `app_id`           | string |          | Numeric web chat app ID. Generated from the surface name on create, so it can be left empty.               |
| `subdomain`        | string |          | Custom domain alias that overrides the default bot domain. For a domain like abc.moveworks.com, enter abc. |
| `surface`          | string |          | Product UI surface where the web chat bot appears. Allowed values: embedded, assistant, employee-slate.    |

**`gchat_config`**

Google Chat settings. Set this when channel is gchat.

| Field                        | Type    | Required | Notes                                                                                                                                   |
| ---------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `app_id`                     | string  |          | Google Chat app ID, which is the bot's email address.                                                                                   |
| `proactive_reachout_enabled` | boolean |          | If true, the bot can proactively reach out to users in Google Chat.                                                                     |
| `credentials_secret`         | string  |          | JSON credentials file generated for the Google Chat app. Secret: always returned masked as \*\*\*\*\*.                                  |
| `deep_link`                  | string  |          | Link users open to chat with the bot, such as a Google Chat bot catalog link or a link from your SSO provider.                          |
| `audience`                   | string  |          | GCP project number of the Google Cloud project that owns the Chat app, used to verify inbound events from Google Chat. Up to 20 digits. |

**`webex_config`**

Webex settings. Set this when channel is webex.

| Field              | Type           | Required | Notes                                                                |
| ------------------ | -------------- | -------- | -------------------------------------------------------------------- |
| `app_id`           | string         |          | Webex app ID, an 86-character alphanumeric string.                   |
| `public_url`       | string         |          | Public URL of the Webex bot.                                         |
| `org_id`           | string         |          | Webex organization ID.                                               |
| `domain_whitelist` | array\<string> |          | Email domains allowed to interact with the Webex bot, e.g. acme.com. |
| `secret_token`     | string         |          | Webex bot API token. Secret: always returned masked as \*\*\*\*\*.   |

**`zoom_config`**

Zoom settings. Set this when channel is zoom.

| Field                     | Type   | Required | Notes                                                                                               |
| ------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `bot_jid`                 | string |          | Zoom bot JID, in the form \<24 characters>@xmpp.zoom.us.                                            |
| `client_id`               | string |          | Zoom app client ID.                                                                                 |
| `account_id`              | string |          | Zoom account ID.                                                                                    |
| `app_id`                  | string |          | Zoom app ID, in the form \<24 characters>@xmpp.zoom.us.                                             |
| `client_secret`           | string |          | Zoom app client secret. Secret: always returned masked as \*\*\*\*\*.                               |
| `verification_secret_key` | string |          | Secret key used to verify inbound messages from Zoom. Secret: always returned masked as \*\*\*\*\*. |
| `s2s_client_id`           | string |          | Client ID of the Zoom Server-to-Server OAuth app.                                                   |
| `s2s_client_secret`       | string |          | Client secret of the Zoom Server-to-Server OAuth app. Secret: always returned masked as \*\*\*\*\*. |

**`glip_config`**

Glip (RingCentral) settings. Set this when channel is glip.

| Field                       | Type   | Required | Notes                                                                                                  |
| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `app_id`                    | string |          | Numeric Glip app ID.                                                                                   |
| `public_url`                | string |          | Public URL of the Glip bot.                                                                            |
| `secret_token`              | string |          | Glip bot token. Secret: always returned masked as \*\*\*\*\*.                                          |
| `verification_secret_token` | string |          | Glip verification token used to verify inbound requests. Secret: always returned masked as \*\*\*\*\*. |

**`sms_config`**

SMS settings. Set this when channel is sms.

| Field    | Type   | Required | Notes                            |
| -------- | ------ | -------- | -------------------------------- |
| `app_id` | string |          | SMS app ID, as a lowercase GUID. |

**`conversations_rest_api_config`**

Conversations REST API settings. Set this when channel is conversationsrestapi; it has no fields.

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |

### Example create body

```json
{
  "assistant_id": "<id>",
  "name": "example-name",
  "slack_config": {
    "app_id": "A0123456789",
    "user_id": "U0123456789",
    "team_id": "T0123456789",
    "assistant_id": "B0123456789",
    "chat_system_url": "https://example.com/path",
    "instance_name": "acme"
  },
  "version": {
    "change_description": "Create surface"
  },
  "channel": "slack"
}
```