Skip to navigation

Conversational Processes

View as Markdown

platform.extensions.conversational-processes

A conversational process is the user-facing flow of a plugin: the slots it collects from the user and the steps it runs, such as actions, branches and replies.

To learn what conversational processes do, see Conversational Processes in the Tool Studio docs.

  • Endpoint: /platform/extensions/conversational-processes | 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 with version: {num, change_description} from your last read. Lists of objects merge row by row, so read first and send the whole list when you remove or reorder rows. See Tool Studio.
  • References: Activities call actions by id (action_id.http_action, compound_action or script_action). Slots of a custom type use the data type’s name. A plugin launches the process through execution_config.conversational_plugin_body_config_uuid, which takes the process’s id.

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/platform/extensions/conversational-processesList conversational processes
POST/platform/extensions/conversational-processesCreate conversational process
GET/platform/extensions/conversational-processes/{id}Get conversational process
PATCH/platform/extensions/conversational-processes/{id}Update conversational process

Rules the API checks

  • The server sets signature.name from signature.display_name. Don’t send it.
  • conversation_flow is one block: sequential, switch, activity, return or noop. Don’t put a sequential block directly inside another sequential block.
  • A switch case can’t have an empty then; use noop.
  • text activity templates use Mustache over data, for example {{ data.purchase_order.status }}.

Fields

FieldTypeRequiredNotes
idstringread-onlyUnique identifier of the conversational process, assigned by the server. Cannot be changed.
signatureFunctionSignatureSettings✅Name and description of the conversational process. The internal name is derived from the display name. Required.
slotsarray<ConversationalProcessSlot>Input values (slots) the process collects from the user and uses as variables in the conversation flow.
conversation_flowConversationBlock✅The control flow of the process, built from sequential, switch, activity, return and no-op blocks. Required.
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.

Example create body

{
"signature": {
"display_name": "Purchase Order Lookup",
"description": "Looks up a purchase order by number and reports its status.",
"name": "example"
},
"slots": [
{
"name": "po_number",
"description": "The purchase order number the user is asking about.",
"type": {
"primitive": "string"
},
"resolution": {
"must_request": true,
"value_population_policy": {
"inference_type": "CONVERSATIONAL_PROCESS_INFERENCE_TYPE_ALWAYS_INFER"
}
}
}
],
"conversation_flow": {
"sequential": {
"steps": [
{
"activity": {
"prerequisite_slots": [
"po_number"
],
"output_slot": "purchase_order",
"action": {
"action_id": {
"http_action": "1b7d4f5a-2c88-4e0b-9f31-7c5a0d9e4411"
},
"input_mapper": {
"po_number": "data.po_number"
}
},
"needs_confirmation": false
}
},
{
"return": {}
}
]
}
},
"version": {
"change_description": "Initial version."
}
}