> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# SendUserMessage

# Package: forms

# Namespace: InteractiveFormSessionsService

# Method link: https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions/send-user-message.md

## Permission Scopes:
Manage form submissions.: SCOPE.FORMS.MANAGE-SUBMISSIONS

## Introduction

Submits a user message to an existing interactive form session and processes the conversational input.
User messages support up to 10,000 characters.

For implementations that require real-time streaming, call [Send User Message Streamed](https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions/send-user-message-streamed.md) instead.

---

## REST API

### Schema

```
 Method: sendUserMessage
 Description: Submits a user message to an existing interactive form session and processes the conversational input. User messages support up to 10,000 characters.  For implementations that require real-time streaming, call [Send User Message Streamed](https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions/send-user-message-streamed.md) instead.
 URL: https://www.wixapis.com/forms/ai/v1/interactive-form-sessions/{interactiveFormSessionId}/send-user-message
 Method: POST
 Method parameters:
   param name: currentValues | type: currentValues | description: Form field values to apply to the session. Use this to update form data from other sources while the conversation is ongoing. These values override any existing data for the same field keys. For example: `{"lastName": "Smith", "phoneNumber": "+1234567890"}`. 
   param name: input | type: input | description: User's natural language input. The AI assistant analyzes this text to extract form field data and determine the next conversation step. Maximum length: 10,000 characters. 
 Return type: SendUserMessageResponse
  - name: interactiveFormSession | type: InteractiveFormSession | description: Updated interactive form session after the user input is processed. 
     - name: id | type: string | description: Interactive form session GUID. 
     - name: formId | type: string | description: Form GUID. 
  - name: responseChunks | type: array<InteractiveFormSessionResponseChunk> | description: AI assistant response chunks generated from processing the user's message. These can include extracted data, follow-up questions, input selectors, or submission confirmation. 
     - ONE-OF: 
        - name: textDetails | type: TextDetails | description: Conversational text message for display. 
           - name: text | type: string | description: Text content to display. 
           - name: style | type: Style | description: Text formatting style for visual presentation. 
                 - enum:
                 -     NORMAL: Regular conversational text.
                 -     BOLD: Bold text for emphasis.
        - name: textDataDetails | type: TextDataDetails | description: Structured data extracted from user input and mapped to specific form fields. 
           - name: fieldTarget | type: string | description: Form field identifier that this extracted data maps to. Matches a field name in the form schema. 
           - name: text | type: string | description: Human-readable text representation of the extracted data to display. 
           - name: value | type: Value | description: Structured value for form submission (for example, boolean `true`/`false`, number, or string). This is the actual data value that will be submitted with the form. 
              - ONE-OF: 
                 - name: nullValue | type:  | description:  
                 - name: numberValue | type: number | description:  
                 - name: stringValue | type: string | description:  
                 - name: boolValue | type: boolean | description:  
                 - name: structValue | type: object | description:  
                 - name: listValue | type: ListValue | description:  
                    - name: values | type: array<Value> | description:  
           - name: displayValue | type: string | description: User-friendly display representation of the value (for example, "Yes"/"No" for boolean, "25 years old" for age). Use this to display confirmation of what was extracted from the user's input. 
        - name: multiSelectInputDetails | type: MultiSelectInputDetails | description: Selector for selecting multiple options from a predefined list. 
           - name: fieldTarget | type: string | description: Form field identifier for the multi-select input. 
           - name: options | type: array<Option> | description: Options available for selection, when relevant. Users can choose multiple options from this list. 
              - name: value | type: string | description: Value to be submitted when this option is selected. This is the technical value used in form processing and submission. 
              - name: label | type: string | description: Human-readable label for display for this option. 
           - name: allowedCustomValue | type: CustomValue | description: When present, allows users to provide custom values not in the predefined options list. 
              - name: description | type: string | description: Description of the expected custom value format or content. Displayed to guide users when they choose to provide a custom option. 
        - name: numberInputDetails | type: NumberInputDetails | description: Selector for numeric input with optional range and validation constraints. 
           - name: fieldTarget | type: string | description: Form field identifier for the numeric input. 
           - name: rangeLimit | type: NumberRangeLimit | description: Minimum and maximum value constraints for the numeric input. 
              - ONE-OF: 
                 - name: maxInclusiveValue | type: number | description: Maximum allowed value (inclusive). 
                 - name: maxExclusiveValue | type: number | description: Maximum allowed value (exclusive). 
              - name: minInclusiveValue | type: number | description: Minimum allowed value (inclusive). 
           - name: multipleOf | type: number | description: When provided, restricts input to multiples of this value. For example, `2.5` would allow 2.5, 5.0, 7.5, and so on. 
        - name: separatorDetails | type: SeparatorDetails | description: Visual separator element for organizing conversation flow. 
           - name: type | type: Type | description: Type of visual separator to display in the conversation flow. 
                 - enum:
                 -     PARAGRAPH: Paragraph break for visual content separation.
        - name: singleSelectInputDetails | type: SingleSelectInputDetails | description: Selector for selecting a single option from a predefined list. 
           - name: fieldTarget | type: string | description: Form field identifier for the single-select input. 
           - name: options | type: array<Option> | description: Options available for selection. Users can choose only one option from this list. 
           - name: allowedCustomValue | type: CustomValue | description: When present, allows users to provide a custom value not in the predefined options list. 
        - name: errorDetails | type: ErrorDetails | description: Error information when processing fails or validation errors occur. 
           - name: messageText | type: string | description: Error message detailing what went wrong during processing. For display to the user when the AI cannot process their input or when validation fails. 
        - name: submissionDetails | type: SubmissionDetails | description: Form submission confirmation including a form submission GUID. A checkout GUID will also be returned here if the user selected products for purchase. 
           - name: submissionId | type: string | description: Form submission GUID created when the form is successfully completed and submitted. 
           - name: checkoutId | type: string | description: Wix eCommerce checkout GUID when the form includes payment processing. Only present for forms that have payment fields or are connected to eCommerce flows. 
        - name: importantTextDetails | type: ImportantTextDetails | description: Important contextual information that may influence data extraction or user decisions. 
           - name: fieldTarget | type: string | description: Form field identifier that this important information relates to. 
           - name: text | type: string | description: Important contextual information to highlight. This might include validation requirements, format expectations, or clarifying questions. 
        - name: debugDetails | type: DebugDetails | description: Diagnostic information for development, debugging, and performance monitoring. 
           - name: data | type: object | description: Diagnostic data for development and troubleshooting. Contains information such as AI tools called, processing times, and internal state. 
        - name: endOfResponseDetails | type: EndOfResponseDetails | description: Stream completion signal indicating no more chunks will be sent in this response. 
           - name: success | type: boolean | description: Whether the response stream completed successfully. When `false`, there may have been processing errors or interruptions. 
        - name: fileUploadDetails | type: FileUploadDetails | description: Input for file upload with field targeting. Not supported. 
           - name: fieldTarget | type: string | description: Form field identifier for the file upload input. 
        - name: signatureDetails | type: SignatureDetails | description: Input for digital signature capture with field targeting. Not supported. 
           - name: fieldTarget | type: string | description: Form field identifier for the digital signature input. 
     - name: chunkType | type: ChunkType | description: Response chunk type, that determines how the content should be processed and displayed. 
         - enum:
         -     TEXT: Text message for display to the user.
         -     TEXT_DATA: Structured data extracted from user input and mapped to form fields.
         -     MULTI_SELECT_INPUT: Selector for selecting multiple options from a list.
         -     NUMBER_INPUT: Selector for numeric input with optional validation.
         -     SEPARATOR: Visual separator element such as paragraph breaks.
         -     SINGLE_SELECT_INPUT: Selector for selecting one option from a list.
         -     ERROR: Error message when processing fails or validation errors occur.
         -     SUBMISSION: Form submission confirmation including a submission ID.
         -     IMPORTANT_TEXT: Highlighted information that may influence form data extraction.
         -     DEBUG: Diagnostic information for troubleshooting and development.
         -     END_OF_RESPONSE: Signals the completion of a response stream.
         -     FILE_UPLOAD: Input for file upload. Not supported.
         -     SIGNATURE: Input for digital signature capture. Not supported.
     - name: meaningfulInput | type: MeaningfulInput | description: Indicates which portion of the original user input was meaningful for data extraction. Can be used to highlight relevant parts of the user's message in the UI. 
        - name: startOffset | type: integer | description: Character position (0-indexed) where the meaningful portion of user input begins. 
        - name: length | type: integer | description: Length in characters of the meaningful portion of user input. Use this with `startOffset` to highlight the relevant text that was processed for data extraction. 

 Possible Errors:
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: EMPTY_REQUEST | Description: Request message was empty or session GUID is invalid.


```

### Examples

### Send User Message
```curl
curl -X POST "https://www.wixforms.com/_api/form-ai-assistant/v1/interactive-form-sessions/session-12345678-1234-1234-1234-123456789abc/send-user-message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "input": "My name is Jane Smith and I work as a software engineer at Tech Corp.",
    "current_values": {
      "name": "Jane Smith",
      "occupation": "Software Engineer"
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.forms.InteractiveFormSessionsService.sendUserMessage(interactiveFormSessionId, options)
 Description: Submits a user message to an existing interactive form session and processes the conversational input. User messages support up to 10,000 characters.  For implementations that require real-time streaming, call [Send User Message Streamed](https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions/send-user-message-streamed.md) instead.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  interactiveFormSessionId
 Method parameters: 
   param name: interactiveFormSessionId | type: string | description: Interactive form session GUID to send the message to. | required: true
   param name: options | type: SendUserMessageOptions  none 
        - name: input | type: string | description: User's natural language input. The AI assistant analyzes this text to extract form field data and determine the next conversation step. Maximum length: 10,000 characters. 
        - name: currentValues | type: object | description: Form field values to apply to the session. Use this to update form data from other sources while the conversation is ongoing. These values override any existing data for the same field keys. For example: `{"lastName": "Smith", "phoneNumber": "+1234567890"}`. 
 Return type: PROMISE<SendUserMessageResponse>
  - name: interactiveFormSession | type: InteractiveFormSession | description: Updated interactive form session after the user input is processed. 
     - name: _id | type: string | description: Interactive form session GUID. 
     - name: formId | type: string | description: Form GUID. 
  - name: responseChunks | type: array<InteractiveFormSessionResponseChunk> | description: AI assistant response chunks generated from processing the user's message. These can include extracted data, follow-up questions, input selectors, or submission confirmation. 
     - ONE-OF: 
        - name: textDetails | type: TextDetails | description: Conversational text message for display. 
           - name: text | type: string | description: Text content to display. 
           - name: style | type: Style | description: Text formatting style for visual presentation. 
                 - enum:
                 -     NORMAL: Regular conversational text.
                 -     BOLD: Bold text for emphasis.
        - name: textDataDetails | type: TextDataDetails | description: Structured data extracted from user input and mapped to specific form fields. 
           - name: fieldTarget | type: string | description: Form field identifier that this extracted data maps to. Matches a field name in the form schema. 
           - name: text | type: string | description: Human-readable text representation of the extracted data to display. 
           - name: value | type: Value | description: Structured value for form submission (for example, boolean `true`/`false`, number, or string). This is the actual data value that will be submitted with the form. 
              - ONE-OF: 
                 - name: nullValue | type:  | description:  
                 - name: numberValue | type: number | description:  
                 - name: stringValue | type: string | description:  
                 - name: boolValue | type: boolean | description:  
                 - name: structValue | type: object | description:  
                 - name: listValue | type: ListValue | description:  
                    - name: values | type: array<Value> | description:  
           - name: displayValue | type: string | description: User-friendly display representation of the value (for example, "Yes"/"No" for boolean, "25 years old" for age). Use this to display confirmation of what was extracted from the user's input. 
        - name: multiSelectInputDetails | type: MultiSelectInputDetails | description: Selector for selecting multiple options from a predefined list. 
           - name: fieldTarget | type: string | description: Form field identifier for the multi-select input. 
           - name: options | type: array<Option> | description: Options available for selection, when relevant. Users can choose multiple options from this list. 
              - name: value | type: string | description: Value to be submitted when this option is selected. This is the technical value used in form processing and submission. 
              - name: label | type: string | description: Human-readable label for display for this option. 
           - name: allowedCustomValue | type: CustomValue | description: When present, allows users to provide custom values not in the predefined options list. 
              - name: description | type: string | description: Description of the expected custom value format or content. Displayed to guide users when they choose to provide a custom option. 
        - name: numberInputDetails | type: NumberInputDetails | description: Selector for numeric input with optional range and validation constraints. 
           - name: fieldTarget | type: string | description: Form field identifier for the numeric input. 
           - name: rangeLimit | type: NumberRangeLimit | description: Minimum and maximum value constraints for the numeric input. 
              - ONE-OF: 
                 - name: maxInclusiveValue | type: number | description: Maximum allowed value (inclusive). 
                 - name: maxExclusiveValue | type: number | description: Maximum allowed value (exclusive). 
              - name: minInclusiveValue | type: number | description: Minimum allowed value (inclusive). 
           - name: multipleOf | type: number | description: When provided, restricts input to multiples of this value. For example, `2.5` would allow 2.5, 5.0, 7.5, and so on. 
        - name: separatorDetails | type: SeparatorDetails | description: Visual separator element for organizing conversation flow. 
           - name: type | type: Type | description: Type of visual separator to display in the conversation flow. 
                 - enum:
                 -     PARAGRAPH: Paragraph break for visual content separation.
        - name: singleSelectInputDetails | type: SingleSelectInputDetails | description: Selector for selecting a single option from a predefined list. 
           - name: fieldTarget | type: string | description: Form field identifier for the single-select input. 
           - name: options | type: array<Option> | description: Options available for selection. Users can choose only one option from this list. 
           - name: allowedCustomValue | type: CustomValue | description: When present, allows users to provide a custom value not in the predefined options list. 
        - name: errorDetails | type: ErrorDetails | description: Error information when processing fails or validation errors occur. 
           - name: messageText | type: string | description: Error message detailing what went wrong during processing. For display to the user when the AI cannot process their input or when validation fails. 
        - name: submissionDetails | type: SubmissionDetails | description: Form submission confirmation including a form submission GUID. A checkout GUID will also be returned here if the user selected products for purchase. 
           - name: submissionId | type: string | description: Form submission GUID created when the form is successfully completed and submitted. 
           - name: checkoutId | type: string | description: Wix eCommerce checkout GUID when the form includes payment processing. Only present for forms that have payment fields or are connected to eCommerce flows. 
        - name: importantTextDetails | type: ImportantTextDetails | description: Important contextual information that may influence data extraction or user decisions. 
           - name: fieldTarget | type: string | description: Form field identifier that this important information relates to. 
           - name: text | type: string | description: Important contextual information to highlight. This might include validation requirements, format expectations, or clarifying questions. 
        - name: debugDetails | type: DebugDetails | description: Diagnostic information for development, debugging, and performance monitoring. 
           - name: data | type: object | description: Diagnostic data for development and troubleshooting. Contains information such as AI tools called, processing times, and internal state. 
        - name: endOfResponseDetails | type: EndOfResponseDetails | description: Stream completion signal indicating no more chunks will be sent in this response. 
           - name: success | type: boolean | description: Whether the response stream completed successfully. When `false`, there may have been processing errors or interruptions. 
        - name: fileUploadDetails | type: FileUploadDetails | description: Input for file upload with field targeting. Not supported. 
           - name: fieldTarget | type: string | description: Form field identifier for the file upload input. 
        - name: signatureDetails | type: SignatureDetails | description: Input for digital signature capture with field targeting. Not supported. 
           - name: fieldTarget | type: string | description: Form field identifier for the digital signature input. 
     - name: chunkType | type: ChunkType | description: Response chunk type, that determines how the content should be processed and displayed. 
         - enum:
         -     TEXT: Text message for display to the user.
         -     TEXT_DATA: Structured data extracted from user input and mapped to form fields.
         -     MULTI_SELECT_INPUT: Selector for selecting multiple options from a list.
         -     NUMBER_INPUT: Selector for numeric input with optional validation.
         -     SEPARATOR: Visual separator element such as paragraph breaks.
         -     SINGLE_SELECT_INPUT: Selector for selecting one option from a list.
         -     ERROR: Error message when processing fails or validation errors occur.
         -     SUBMISSION: Form submission confirmation including a submission ID.
         -     IMPORTANT_TEXT: Highlighted information that may influence form data extraction.
         -     DEBUG: Diagnostic information for troubleshooting and development.
         -     END_OF_RESPONSE: Signals the completion of a response stream.
         -     FILE_UPLOAD: Input for file upload. Not supported.
         -     SIGNATURE: Input for digital signature capture. Not supported.
     - name: meaningfulInput | type: MeaningfulInput | description: Indicates which portion of the original user input was meaningful for data extraction. Can be used to highlight relevant parts of the user's message in the UI. 
        - name: startOffset | type: integer | description: Character position (0-indexed) where the meaningful portion of user input begins. 
        - name: length | type: integer | description: Length in characters of the meaningful portion of user input. Use this with `startOffset` to highlight the relevant text that was processed for data extraction. 

 Possible Errors:
   HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: EMPTY_REQUEST | Description: Request message was empty or session GUID is invalid.


```

### Examples

### Send user message to interactive form session
```javascript
import { interactiveFormSessions } from "@wix/forms";

const currentValues = {
  name: "Jane Smith",
  occupation: "Software Engineer",
};

async function sendUserMessage() {
  const response = await interactiveFormSessions.sendUserMessage(
    "session-12345678-1234-1234-1234-123456789abc",
    {
      input: "My name is Jane Smith and I work as a software engineer at Tech Corp.",
      currentValues,
    }
  );
}

```

### sendUserMessage (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { interactiveFormSessions } from '@wix/forms';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { interactiveFormSessions },
  // Include the auth strategy and host as relevant
});


async function sendUserMessage(interactiveFormSessionId,options) {
  const response = await myWixClient.interactiveFormSessions.sendUserMessage(interactiveFormSessionId,options);
};
```

---