> 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

# CreateInteractiveFormSession

# Package: forms

# Namespace: InteractiveFormSessionsService

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

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

## Introduction

Creates an interactive form session for AI-powered conversational form completion.

For implementations that require real-time streaming, call [Create Interactive Form Session Streamed](https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions/create-interactive-form-session-streamed.md) instead.

---

## REST API

### Schema

```
 Method: createInteractiveFormSession
 Description: Creates an interactive form session for AI-powered conversational form completion.  For implementations that require real-time streaming, call [Create Interactive Form Session Streamed](https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions/create-interactive-form-session-streamed.md) instead.
 URL: https://www.wixapis.com/forms/ai/v1/interactive-form-sessions
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  formId
 Method parameters: 
   param name: clientTime | type: ClientTime   
        - name: currentTime | type: string | description: Current date and time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. For example, `2023-10-01T12:00:00Z`. 
        - name: timeZone | type: string | description: Browser's timezone identifier for localizing date and time values in IANA timezone format (for example, `Europe/Vilnius`, `America/New_York`). 
   param name: currentValues | type: currentValues | description: Pre-filled values to apply to the form, to initialize the session with existing data. Field keys must match the form schema field names. For example: `{"firstName": "John", "email": "john@example.com", "age": 25}`. These values are merged with any data extracted during the conversation. 
   param name: dryRun | type: dryRun | description: Whether the session should run in dry run mode for testing and preview purposes. In dry run mode, the full conversational flow works normally and form data is extracted, but no actual form submission occurs. 
   param name: formId | type: formId | description: Form GUID to create an interactive session for. | required: true
 Return type: CreateInteractiveFormSessionResponse
  - name: interactiveFormSession | type: InteractiveFormSession | description: Created interactive form session. 
     - 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 for the interactive form session. 
     - 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. 


```

### Examples

### Create Interactive Form Session
```curl
curl -X POST "https://www.wixforms.com/_api/form-ai-assistant/v1/interactive-form-sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "form_id": "12345678-1234-1234-1234-123456789abc",
    "prompt_id": "87654321-4321-4321-4321-cba987654321",
    "current_values": {
      "name": "John Doe",
      "email": "john.doe@example.com"
    },
    "dry_run": false,
    "current_time": "2024-01-15T14:30:00+02:00"
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.forms.InteractiveFormSessionsService.createInteractiveFormSession(formId, options)
 Description: Creates an interactive form session for AI-powered conversational form completion.  For implementations that require real-time streaming, call [Create Interactive Form Session Streamed](https://dev.wix.com/docs/api-reference/crm/forms/interactive-form-sessions/create-interactive-form-session-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:  formId
 Method parameters: 
   param name: formId | type: string | description: Form GUID to create an interactive session for. | required: true
   param name: options | type: CreateInteractiveFormSessionOptions  none 
        - name: currentValues | type: object | description: Pre-filled values to apply to the form, to initialize the session with existing data. Field keys must match the form schema field names. For example: `{"firstName": "John", "email": "john@example.com", "age": 25}`. These values are merged with any data extracted during the conversation. 
        - name: dryRun | type: boolean | description: Whether the session should run in dry run mode for testing and preview purposes. In dry run mode, the full conversational flow works normally and form data is extracted, but no actual form submission occurs. 
        - name: clientTime | type: ClientTime | description: Current date-time of api client. 
           - name: currentTime | type: string | description: Current date and time in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. For example, `2023-10-01T12:00:00Z`. 
           - name: timeZone | type: string | description: Browser's timezone identifier for localizing date and time values in IANA timezone format (for example, `Europe/Vilnius`, `America/New_York`). 
 Return type: PROMISE<InteractiveFormSession>
  - name: _id | type: string | description: Interactive form session GUID. 
  - name: formId | type: string | description: Form GUID. 


```

### Examples

### Create interactive form session
```javascript
import { interactiveFormSessions } from "@wix/forms";

const currentValues = {
  name: "John Doe",
  email: "john.doe@example.com",
};

async function createInteractiveFormSession() {
  const response = await interactiveFormSessions.createInteractiveFormSession(
    "12345678-1234-1234-1234-123456789abc",
    {
      currentValues,
      dryRun: false,
      clientTime: { currentTime: "2024-01-15T14:30:00+02:00" },
    }
  );
}

```

### createInteractiveFormSession (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 createInteractiveFormSession(formId,options) {
  const response = await myWixClient.interactiveFormSessions.createInteractiveFormSession(formId,options);
};
```

---