Skip to navigation

Surfaces

View as Markdown

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.

MethodPathEndpoint reference
GET/assistant/surfacesList surfaces
POST/assistant/surfacesCreate surface
GET/assistant/surfaces/{id}Get surface
PATCH/assistant/surfaces/{id}Update surface

Fields

FieldTypeRequiredNotes
idstringread-onlyUnique ID of this configuration, assigned by the server.
assistant_idstringBot 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.
namestringUnique 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_namestringCustomer-facing display name of the bot, usually the same across all of an organization’s bots.
channelenum✅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_idstringConnector 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_enabledbooleanIf true, users can send file attachments to the bot.
updated_timestringread-onlyWhen the configuration was last updated.
updated_bystringread-onlyWho last updated the configuration.
versionVersion✅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.

FieldTypeRequiredNotes
app_idstringMicrosoft Teams app ID, as a lowercase GUID.
app_guidstringMicrosoft Teams app GUID, as shown in the Teams client. Needed when the bot was installed with the Teams app registration method.
tenant_idstringMicrosoft Teams (Entra) tenant ID, as a lowercase GUID.
msteams_app_store_credentialsMSTeamsAppStoreCredentialsUse 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_secretstringMicrosoft 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_authMSTeamsOauth2JwtClientAssertionAuthCertificate-based authentication using OAuth2 client credentials with a JWT assertion. Set this, msteams_app_store_credentials or credentials_secret.
regionenumMicrosoft 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_enabledbooleanIf 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.

FieldTypeRequiredNotes
app_idstringSlack app ID, starting with A.
user_idstringSlack user ID of the bot, starting with U or W.
team_idstringSlack team (workspace) or enterprise ID, starting with T or E.
assistant_idstringSlack bot ID, starting with B.
chat_system_urlstringURL of your Slack workspace, e.g. https://acme.slack.com.
instance_namestringName of your Slack instance.
signing_secretstringSlack signing secret used to verify requests sent by Slack. Secret: always returned masked as *****.
regionstringSlack cloud hosting the app. Allowed values: COMMERCIAL, GOV. Use GOV only if the Slack app is hosted in the GOV cloud.
allow_multiple_threadsbooleanIf 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.

FieldTypeRequiredNotes
on_prem_agent_idstringID of the on-premises agent used by this web chat bot.
app_idstringNumeric web chat app ID. Generated from the surface name on create, so it can be left empty.
subdomainstringCustom domain alias that overrides the default bot domain. For a domain like abc.moveworks.com, enter abc.
surfacestringProduct 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.

FieldTypeRequiredNotes
app_idstringGoogle Chat app ID, which is the bot’s email address.
proactive_reachout_enabledbooleanIf true, the bot can proactively reach out to users in Google Chat.
credentials_secretstringJSON credentials file generated for the Google Chat app. Secret: always returned masked as *****.
deep_linkstringLink users open to chat with the bot, such as a Google Chat bot catalog link or a link from your SSO provider.
audiencestringGCP 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.

FieldTypeRequiredNotes
app_idstringWebex app ID, an 86-character alphanumeric string.
public_urlstringPublic URL of the Webex bot.
org_idstringWebex organization ID.
domain_whitelistarray<string>Email domains allowed to interact with the Webex bot, e.g. acme.com.
secret_tokenstringWebex bot API token. Secret: always returned masked as *****.

zoom_config

Zoom settings. Set this when channel is zoom.

FieldTypeRequiredNotes
bot_jidstringZoom bot JID, in the form <24 characters>@xmpp.zoom.us.
client_idstringZoom app client ID.
account_idstringZoom account ID.
app_idstringZoom app ID, in the form <24 characters>@xmpp.zoom.us.
client_secretstringZoom app client secret. Secret: always returned masked as *****.
verification_secret_keystringSecret key used to verify inbound messages from Zoom. Secret: always returned masked as *****.
s2s_client_idstringClient ID of the Zoom Server-to-Server OAuth app.
s2s_client_secretstringClient 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.

FieldTypeRequiredNotes
app_idstringNumeric Glip app ID.
public_urlstringPublic URL of the Glip bot.
secret_tokenstringGlip bot token. Secret: always returned masked as *****.
verification_secret_tokenstringGlip verification token used to verify inbound requests. Secret: always returned masked as *****.

sms_config

SMS settings. Set this when channel is sms.

FieldTypeRequiredNotes
app_idstringSMS app ID, as a lowercase GUID.

conversations_rest_api_config

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

FieldTypeRequiredNotes

Example create body

{
"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"
}