Initialize Chat Session
Initialize an app or skill debug chat session and retrieve welcome text, variables, module settings, and conversation state.
Endpoint Overview
- Method :
GET - Path :
/api/core/chat/init - Module : Chat / Chat History
- Authentication :
Authorization: Bearer <apiKey>—Supports App API Key (appIdoptional) and Personal API Key (appIdrequired); also supportsauthProxyteam member proxy (see API Getting Started ) - Interactive Try-It-Out : Open in Scalar API Explorer (self-hosted instances: replace the origin with
<instance>/apidoc/systemopenapi#tag/%E4%BC%9A%E8%AF%9D%E7%AE%A1%E7%90%86/GET/core/chat/init)
Description & Notes
Initializes an application chat session or a Skill Edit debug session, returning chat configuration, variables, and existing conversation state.
Pass either appId (app chat) or skillId (skill debug) together with chatId in Query parameters ( skillId takes precedence if both are provided).
For builder assistant sessions, pass appId with sourceType ( chatAgentHelper or workflowBuilder ); omit sourceType for regular app chats.
Share-link sessions use GET /api/core/chat/outLink/init with JSON-serialized outLinkAuthData . Starting or resuming a skill runtime sandbox uses POST /api/core/ai/skill/runtime/init .
Request Parameters
Query Parameters
Shared Parameters Across Branches
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
chatId | string | Yes | - | Chat ID. minLength: 1; maxLength: 1024 |
loadCustomFeedbacks | boolean | No | - | Whether to load custom feedback items |
Mutually Exclusive Branches ( anyOf )
- App Chat
Identify the conversation via appId . When both API Key and login session are supported, Authorization takes precedence over token/Cookie.
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
appId | string | Yes | - | Application ID authenticated with the request header credentials allowed by this endpoint. pattern: ^[0-9a-fA-F]{24}$ |
sourceType | string (enum) | No | - | Session resource type associated with appId . Defaults to app ; pass the matching sourceType for assistant builder sessions. Allowed values: app , chatAgentHelper , workflowBuilder |
Default Identity : Omit customUid and authProxy to execute using the team member identity associated with the credential.
Custom end user ( customUid ): Tag end users from your own system via customUid without changing the authenticating member or permissions. Passed as workflow userId and used to scope chat management.
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
customUid | string | Yes | - | Supported only for standard app API Key calls. Exact match against the external user ID ( outLinkUid , not tmbId ). Omit to keep full scope or pass to restrict reads, updates, and deletions (max 1024 chars, cannot be empty or null , does not change member identity). minLength: 1; maxLength: 1024 |
Proxy Team Member ( authProxy ): Act on behalf of another member in the same team via authProxy . Available only on personal API keys with authProxy enabled; mutually exclusive with customUid .
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
authProxy | string | Yes | - | JSON-serialized proxy identity, e.g. {"tmbId":"member-id"} or {"username":"alice"} |
- Skill Debug Session
Identify the debug session via skillId (takes precedence over appId and ignores sourceType ), authenticated with allowed request header credentials.
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
skillId | string | Yes | - | Skill Edit debug ID authenticated with allowed request header credentials. pattern: ^[0-9a-fA-F]{24}$ |
- App API Key (no appId required)
When authorizing with an app-bound App API Key, omit appId and sourceType ; the server resolves the bound app with sourceType fixed to app . Personal keys and login sessions cannot omit appId , and an explicit appId does not override an App API Key binding.
Default Identity : Omit customUid and authProxy to execute using the team member identity associated with the credential.
Custom end user ( customUid ): Tag end users from your own system via customUid without changing the authenticating member or permissions. Passed as workflow userId and used to scope chat management.
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
customUid | string | Yes | - | Supported only for standard app API Key calls. Exact match against the external user ID ( outLinkUid , not tmbId ). Omit to keep full scope or pass to restrict reads, updates, and deletions (max 1024 chars, cannot be empty or null , does not change member identity). minLength: 1; maxLength: 1024 |
Request Examples
Replace YOUR_API_KEY and placeholder IDs before running. Self-hosted users should replace the base URL with <instance>/api .
cURL Example
curl --fail-with-body -X GET "https://cloud.fastgpt.io/api/core/chat/init?appId=68ad85a7463006c963799a05&chatId=1234567890" \
-H "Authorization: Bearer YOUR_API_KEY"Response Schema & Examples
Successful /api/* calls return the standard FastGPT envelope { "code": 200, "statusText": "", "message": "", "data": ... } , where data matches the 200 schema below (when a payload schema is declared; otherwise refer to the status description for runtime data semantics).
HTTP 200
Successfully returned chat initialization data
Content-Type : application/json
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
chatId | string | No | - | Chat ID. maxLength: 1024 |
userAvatar | string | No | - | User avatar URL |
title | string | Yes | - | Chat title |
variables | object | No | - | Global variable values |
chatGenerateStatus | number (enum) | No | - | Live generation status from Redis lease: 0 ( generating ), 1 ( done / idle). Allowed values: 0 , 1 |
hasBeenRead | boolean | No | - | Whether the conversation has been read |
app | object | Yes | - | Application configuration |
app.chatConfig | object | No | - | Chat configuration |
app.chatConfig.welcomeText | string | No | - | Welcome message displayed when starting a new conversation |
app.chatConfig.welcomeConfig | object | No | - | Opening prompt configuration |
app.chatConfig.welcomeConfig.welcomeText | string | No | - | Welcome message displayed when starting a new conversation |
app.chatConfig.welcomeConfig.welcomeQuestions | string[] | No | - | Suggested starter questions shown below the welcome text |
app.chatConfig.variables | object[] | No | - | List of variables users fill in before starting a conversation |
app.chatConfig.variables[].maxFiles | integer | No | - | Maximum number of files allowed for this variable. min: 0; max: 9007199254740991 |
app.chatConfig.variables[].canSelectFile | boolean | No | - | Whether regular document files are allowed for this variable |
app.chatConfig.variables[].customPdfParse | boolean | No | - | Whether custom PDF parsing is enabled |
app.chatConfig.variables[].canSelectImg | boolean | No | - | Whether images are allowed for this variable |
app.chatConfig.variables[].canSelectVideo | boolean | No | - | Whether videos are allowed for this variable |
app.chatConfig.variables[].canSelectAudio | boolean | No | - | Whether audio files are allowed for this variable |
app.chatConfig.variables[].canSelectCustomFileExtension | boolean | No | - | Whether custom file extensions are allowed for this variable |
app.chatConfig.variables[].customFileExtensionList | string[] | No | - | List of allowed custom file extensions for this variable |
app.chatConfig.variables[].key | string | Yes | - | Variable key used in prompts and workflow references |
app.chatConfig.variables[].label | string | Yes | - | Variable display label |
app.chatConfig.variables[].valueType | string (enum) | No | - | Variable value data type. Allowed values: string , number , boolean , object , arrayString , arrayNumber , arrayBoolean , arrayObject , arrayAny , any , chatHistory , datasetQuote , dynamic , selectDataset , selectApp |
app.chatConfig.variables[].required | boolean | No | - | Whether this variable is required |
app.chatConfig.variables[].defaultValue | object | array | string | number | boolean | null | No | - | Default value for the variable |
app.chatConfig.variables[].referencePlaceholder | string | No | - | Placeholder text displayed when referencing the variable |
app.chatConfig.variables[].isRichText | boolean | No | - | Whether rich-text input is enabled |
app.chatConfig.variables[].placeholder | string | No | - | Input field placeholder text |
app.chatConfig.variables[].maxLength | integer | No | - | Maximum input character length for text variables. min: 0; max: 9007199254740991 |
app.chatConfig.variables[].minLength | integer | No | - | Minimum input character length for text variables. min: 0; max: 9007199254740991 |
app.chatConfig.variables[].markList | object[] | No | - | Scale tick marks for numeric slider variables |
app.chatConfig.variables[].step | number | No | - | Numeric step increment |
app.chatConfig.variables[].max | number | No | - | Maximum numeric value |
app.chatConfig.variables[].min | number | No | - | Minimum numeric value |
app.chatConfig.variables[].precision | number | No | - | Decimal precision for numeric variables |
app.chatConfig.variables[].canLocalUpload | boolean | No | - | Whether local file upload is allowed for this variable |
app.chatConfig.variables[].canUrlUpload | boolean | No | - | Whether importing files by URL is allowed for this variable |
app.chatConfig.variables[].timeGranularity | string (enum) | No | - | Granularity of time selection. Allowed values: day , hour , minute , second |
app.chatConfig.variables[].timeRangeStart | string | No | - | Start timestamp of the time range variable |
app.chatConfig.variables[].timeRangeEnd | string | No | - | End timestamp of the time range variable |
app.chatConfig.variables[].datasetOptions | object[] | No | - | Selectable datasets for dataset-picker variables |
app.chatConfig.variables[].customInputConfig | object | No | - | Custom input configuration in the workflow editor |
app.chatConfig.variables[].type | string (enum) | Yes | - | Variable input component type. Allowed values: input , textarea , numberInput , select , multipleSelect , timePointSelect , timeRangeSelect , switch , password , file , llmSelect , datasetSelect , custom , internal |
app.chatConfig.variables[].description | string | Yes | - | Description of the variable purpose |
app.chatConfig.variables[].list | object[] | No | - | Options for select-type variables |
app.chatConfig.variables[].enums | object[] | No | - | Deprecated . Deprecated: legacy enum options |
app.chatConfig.autoExecute | object | No | - | Auto-execute configuration |
app.chatConfig.autoExecute.open | boolean | Yes | - | Whether to trigger execution automatically when opening a chat |
app.chatConfig.autoExecute.defaultPrompt | string | Yes | "" | Default prompt injected during auto-execution |
app.chatConfig.questionGuide | object | No | - | Follow-up question suggestion configuration |
app.chatConfig.questionGuide.open | boolean | Yes | - | Whether follow-up question suggestions are enabled |
app.chatConfig.questionGuide.modelId | string | No | - | Model ID used to generate follow-up question suggestions |
app.chatConfig.questionGuide.model | string | No | - | Deprecated . Legacy model identifier for follow-up suggestions |
app.chatConfig.questionGuide.customPrompt | string | No | - | Custom prompt appended for follow-up suggestions |
app.chatConfig.ttsConfig | object | No | - | Text-to-speech (TTS) configuration |
app.chatConfig.ttsConfig.type | string (enum) | Yes | - | TTS output mode: disabled, browser TTS, or model TTS. Allowed values: none , web , model |
app.chatConfig.ttsConfig.modelId | string | No | - | TTS model ID used for speech synthesis |
app.chatConfig.ttsConfig.model | string | No | - | Deprecated . TTS model name used for speech synthesis |
app.chatConfig.ttsConfig.voice | string | No | - | TTS voice identifier |
app.chatConfig.ttsConfig.speed | number | No | - | TTS playback speed |
app.chatConfig.whisperConfig | object | No | - | Speech-to-text (STT) input configuration |
app.chatConfig.whisperConfig.open | boolean | Yes | - | Whether voice input transcription is enabled |
app.chatConfig.whisperConfig.autoSend | boolean | Yes | false | Whether to auto-send after voice transcription completes |
app.chatConfig.whisperConfig.autoTTSResponse | boolean | Yes | false | Whether to auto-play TTS replies after voice input |
app.chatConfig.scheduledTriggerConfig | object | No | - | Scheduled trigger configuration |
app.chatConfig.scheduledTriggerConfig.cronString | string | Yes | - | Cron schedule expression |
app.chatConfig.scheduledTriggerConfig.timezone | string | Yes | - | Timezone used by the schedule |
app.chatConfig.scheduledTriggerConfig.defaultPrompt | string | Yes | "" | Default prompt injected on scheduled runs |
app.chatConfig.chatInputGuide | object | No | - | Chat input guide configuration |
app.chatConfig.chatInputGuide.open | boolean | Yes | - | Whether chat input guidance is enabled |
app.chatConfig.chatInputGuide.customUrl | string | Yes | - | Custom input guide page URL |
app.chatConfig.fileSelectConfig | object | No | - | Chat file upload configuration |
app.chatConfig.fileSelectConfig.maxFiles | integer | No | - | Maximum files allowed per chat turn. min: 0; max: 9007199254740991 |
app.chatConfig.fileSelectConfig.canSelectFile | boolean | No | - | Whether document files can be uploaded in chat |
app.chatConfig.fileSelectConfig.customPdfParse | boolean | No | - | Whether custom PDF parsing is enabled |
app.chatConfig.fileSelectConfig.canSelectImg | boolean | No | - | Whether images can be uploaded in chat |
app.chatConfig.fileSelectConfig.canSelectVideo | boolean | No | - | Whether videos can be uploaded in chat |
app.chatConfig.fileSelectConfig.canSelectAudio | boolean | No | - | Whether audio files can be uploaded in chat |
app.chatConfig.fileSelectConfig.canSelectCustomFileExtension | boolean | No | - | Whether custom file extensions are allowed in chat |
app.chatConfig.fileSelectConfig.customFileExtensionList | string[] | No | - | List of allowed custom file extensions in chat |
app.chatConfig.entryPoints | object[] | No | - | Feature menu entries shown on the chat page |
app.chatConfig.entryPoints[].id | string | Yes | - | - |
app.chatConfig.entryPoints[].name | string | Yes | - | - |
app.chatConfig.entryPoints[].icon | string | No | - | - |
app.chatConfig.instruction | string | No | - | Usage instructions shown to users on the chat page |
app.chatModels | string[] | No | - | Chat model |
app.name | string | Yes | - | Application name. minLength: 1 |
app.avatar | string | Yes | - | Application avatar URL |
app.intro | string | Yes | - | Application introduction |
app.canUse | boolean | No | - | Whether the resource is available |
app.type | string (enum) | Yes | - | Application type. Allowed values: folder , toolFolder , simple , chatAgent , advanced , plugin , toolSet , httpToolSet , hidden , tool , httpPlugin |
app.pluginInputs | object[] | Yes | - | Plugin input |
app.pluginInputs[].key | string | Yes | - | Variable key used in prompts and workflow references |
app.pluginInputs[].label | string | Yes | - | Variable display label |
app.pluginInputs[].valueType | string (enum) | No | - | Variable value data type. Allowed values: string , number , boolean , object , arrayString , arrayNumber , arrayBoolean , arrayObject , arrayAny , any , chatHistory , datasetQuote , dynamic , selectDataset , selectApp |
app.pluginInputs[].required | boolean | No | - | Whether this variable is required |
app.pluginInputs[].defaultValue | object | array | string | number | boolean | null | No | - | Default value for the variable |
app.pluginInputs[].referencePlaceholder | string | No | - | Placeholder text displayed when referencing the variable |
app.pluginInputs[].isRichText | boolean | No | - | Whether rich-text input is enabled |
app.pluginInputs[].placeholder | string | No | - | Input field placeholder text |
app.pluginInputs[].maxLength | integer | No | - | Maximum input character length for text variables. min: 0; max: 9007199254740991 |
app.pluginInputs[].minLength | integer | No | - | Minimum input character length for text variables. min: 0; max: 9007199254740991 |
app.pluginInputs[].markList | object[] | No | - | Scale tick marks for numeric slider variables |
app.pluginInputs[].markList[].label | string | Yes | - | Tick label |
app.pluginInputs[].markList[].value | number | Yes | - | Tick numeric value |
app.pluginInputs[].step | number | No | - | Numeric step increment |
app.pluginInputs[].max | number | No | - | Maximum numeric value |
app.pluginInputs[].min | number | No | - | Minimum numeric value |
app.pluginInputs[].precision | number | No | - | Decimal precision for numeric variables |
app.pluginInputs[].canSelectFile | boolean | No | - | Whether regular document files are allowed for this variable |
app.pluginInputs[].canSelectImg | boolean | No | - | Whether images are allowed for this variable |
app.pluginInputs[].canSelectVideo | boolean | No | - | Whether videos are allowed for this variable |
app.pluginInputs[].canSelectAudio | boolean | No | - | Whether audio files are allowed for this variable |
app.pluginInputs[].canSelectCustomFileExtension | boolean | No | - | Whether custom file extensions are allowed for this variable |
app.pluginInputs[].customFileExtensionList | string[] | No | - | List of allowed custom file extensions for this variable |
app.pluginInputs[].canLocalUpload | boolean | No | - | Whether local file upload is allowed for this variable |
app.pluginInputs[].canUrlUpload | boolean | No | - | Whether importing files by URL is allowed for this variable |
app.pluginInputs[].maxFiles | integer | No | - | Maximum number of files allowed for this variable. min: 0; max: 9007199254740991 |
app.pluginInputs[].timeGranularity | string (enum) | No | - | Granularity of time selection. Allowed values: day , hour , minute , second |
app.pluginInputs[].timeRangeStart | string | No | - | Start timestamp of the time range variable |
app.pluginInputs[].timeRangeEnd | string | No | - | End timestamp of the time range variable |
app.pluginInputs[].datasetOptions | object[] | No | - | Selectable datasets for dataset-picker variables |
app.pluginInputs[].datasetOptions[].datasetId | string | Yes | - | Selectable dataset ID |
app.pluginInputs[].datasetOptions[].avatar | string | Yes | - | Selectable dataset icon URL |
app.pluginInputs[].datasetOptions[].name | string | Yes | - | Selectable dataset name |
app.pluginInputs[].datasetOptions[].vectorModel | object | Yes | - | - |
app.pluginInputs[].datasetOptions[].error | string | No | - | - |
app.pluginInputs[].customInputConfig | object | No | - | Custom input configuration in the workflow editor |
app.pluginInputs[].customInputConfig.selectValueTypeList | string (enum)[]` | No | - | Allowed value types for custom variable input |
app.pluginInputs[].customInputConfig.showDefaultValue | boolean | No | - | Whether to show default value settings in the editor |
app.pluginInputs[].customInputConfig.showDescription | boolean | No | - | Whether to show field description settings in the editor |
app.pluginInputs[].customInputConfig.hideBottomDivider | boolean | No | - | Whether to hide the bottom divider in variable editing |
app.pluginInputs[].selectedType | string (enum) | No | - | Active UI render type for multi-type inputs. Allowed values: reference , input , textarea , numberInput , switch , select , multipleSelect , JSONEditor , addInputParam , customVariable , selectApp , selectLLMModel , settingLLMModel , selectDataset , selectDatasetParamsModal , settingDatasetQuotePrompt , hidden , custom , selectSkill , selectTool…… |
app.pluginInputs[].renderTypeList | string (enum)[]` | Yes | - | Allowed UI render types in the workflow editor |
app.pluginInputs[].valueDesc | string | No | - | Human-readable description of the input value |
app.pluginInputs[].value | object | array | string | number | boolean | null | No | - | Current Node.js input value |
app.pluginInputs[].debugLabel | string | No | - | Input label shown in debug mode |
app.pluginInputs[].description | string | No | - | Node.js input description |
app.pluginInputs[].toolDescription | string | No | - | Semantic description when exposed as a tool parameter |
app.pluginInputs[].defaultToAgentGenerated | boolean | No | - | Whether the Agent populates this parameter by default when unset |
app.pluginInputs[].canAgentGenerated | boolean | No | - | Whether Agent auto-generation is allowed for this input |
app.pluginInputs[].customJsonSchema | object | No | - | Custom JSON Schema property definition for tool parameters |
app.pluginInputs[].enum | string | No | - | Deprecated: legacy enum configuration |
app.pluginInputs[].inputList | object[] | No | - | List of system input definitions |
app.pluginInputs[].inputList[].key | string | Yes | - | Input key name |
app.pluginInputs[].inputList[].label | string | Yes | - | Input display label |
app.pluginInputs[].inputList[].description | string | No | - | Input description |
app.pluginInputs[].inputList[].placeholder | string | No | - | Input placeholder text |
app.pluginInputs[].inputList[].required | boolean | No | - | Whether this input is required |
app.pluginInputs[].inputList[].inputType | string (enum) | Yes | - | Input render component type. Allowed values: input , numberInput , secret , switch , select |
app.pluginInputs[].inputList[].value | object | No | - | Default value or secret configuration |
app.pluginInputs[].inputList[].list | object[] | No | - | Options for select-type system inputs |
app.pluginInputs[].canEdit | boolean | No | - | Whether this input can be edited in the editor |
app.pluginInputs[].isPro | boolean | No | - | Whether this input requires a commercial edition |
app.pluginInputs[].isToolOutput | boolean | No | - | Whether this input originates from a tool output |
app.pluginInputs[].deprecated | boolean | No | - | Whether this input is deprecated |
app.pluginInputs[].list | object[] | No | - | Options for select-type variables |
app.pluginInputs[].list[].label | string | Yes | - | Option display label |
app.pluginInputs[].list[].value | string | Yes | - | Option underlying value |
app.pluginInputs[].list[].icon | string | No | - | Option icon |
app.pluginInputs[].list[].description | string | No | - | Option description |
app.pluginInputs[].enums | object[] | No | - | Deprecated . Deprecated: legacy enum options |
app.pluginInputs[].enums[].value | string | Yes | - | Enum option value |
app.pluginInputs[].enums[].label | string | Yes | - | Enum option display label |
app.useAgentSandbox | boolean | No | - | Whether VM execution is enabled |
Mutually Exclusive Branches ( anyOf )
- Option 1
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
appId | string | Yes | - | Application ID; returned only for workflow builder assistant sessions. pattern: ^[0-9a-fA-F]{24}$ |
skillId | any | No | - | - |
sourceType | "workflowBuilder" | Yes | - | Resource type for workflow builder sessions. Fixed: "workflowBuilder" |
- Option 2
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
appId | string | Yes | - | Application ID; returned only for chatAgentHelper sessions. pattern: ^[0-9a-fA-F]{24}$ |
skillId | any | No | - | - |
sourceType | "chatAgentHelper" | Yes | - | Resource type for chatAgentHelper sessions. Fixed: "chatAgentHelper" |
- Option 3
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
appId | string | Yes | - | Application ID; returned only for standard app chat sessions. pattern: ^[0-9a-fA-F]{24}$ |
skillId | any | No | - | - |
- Option 4
| Field | Type | Required | Default | Constraints & Description |
|---|---|---|---|---|
appId | any | No | - | - |
skillId | string | Yes | - | Skill Edit debug ID; returned only for Skill Edit sessions. pattern: ^[0-9a-fA-F]{24}$ |
Last updated