> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # 发送对话消息 > 向对话型应用发送请求。 ## OpenAPI ````yaml /zh/api-reference/openapi_chatflow.json post /chat-messages openapi: 3.0.1 info: title: 工作流编排对话型应用 API (对话流 API) description: >- 对话流应用支持会话持久化，允许将之前的聊天记录作为响应的上下文。对话流应用使用 `advanced-chat` 模式，提供工作流级别的流式事件，用于详细的执行追踪，包括节点开始、完成、迭代和工作流生命周期。 version: 1.0.0 servers: - url: https://{api_base_url} description: 工作流编排对话型应用 API 的基础 URL。自部署时，替换为你的 API 基础 URL。 variables: api_base_url: default: api.dify.ai/v1 description: API 基础 URL 的主机与路径，不含 `https://` 前缀。 security: - ApiKeyAuth: [] tags: - name: 对话流 description: 对话流应用的操作，包括对话消息、工作流执行详情和事件流。 - name: 文件操作 description: 文件上传和预览操作。 - name: 终端用户 description: 终端用户信息相关操作。 - name: 消息反馈 description: 用户反馈操作。 - name: 会话管理 description: 与管理会话相关的操作。 - name: 语音与文字转换 description: 文字转语音和语音转文字操作。 - name: 应用配置 description: 获取应用设置和信息的操作。 - name: 标注管理 description: 与管理标注直接回复相关的操作。 - name: 人工介入 description: 暂停等待人工输入的工作流恢复操作。 paths: /chat-messages: post: tags: - 对话流 summary: 发送对话消息 description: 向对话型应用发送请求。 operationId: sendChatMessageCn requestBody: description: 发送对话消息的请求体。 required: true content: application/json: schema: $ref: '#/components/schemas/ChatRequest' examples: streaming_example: summary: 请求示例 - 流式模式 value: inputs: city: San Francisco query: What are the specs of the iPhone 13 Pro Max? response_mode: streaming conversation_id: '' user: abc-123 files: - type: image transfer_method: remote_url url: https://cloud.dify.ai/logo/logo-site.png blocking_example: summary: 请求示例 - 阻塞模式 value: inputs: {} query: What are the specs of the iPhone 13 Pro Max? response_mode: blocking conversation_id: 45701982-8118-4bc5-8e9b-64562b4555f2 user: abc-123 responses: '200': description: >- 请求成功。内容类型和结构取决于请求中的 `response_mode` 参数。 - 如果 `response_mode` 为 `blocking`，返回 `application/json` 和 `ChatCompletionResponse` 对象。 - 如果 `response_mode` 为 `streaming`，返回 `text/event-stream` 和服务器发送事件流。 content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' examples: blockingResponse: summary: 响应示例 - 阻塞模式 value: event: message task_id: c3800678-a077-43df-a102-53f23ed20b88 id: b01a39de-3480-4f3e-9f1e-4841a80f8e5e message_id: 9da23599-e713-473b-982c-4328d4f5c78a conversation_id: 45701982-8118-4bc5-8e9b-64562b4555f2 mode: advanced-chat answer: iPhone 13 Pro Max specs are listed here:... metadata: usage: prompt_tokens: 1033 prompt_unit_price: '0.001' prompt_price_unit: '0.001' prompt_price: '0.0010330' completion_tokens: 128 completion_unit_price: '0.002' completion_price_unit: '0.001' completion_price: '0.0002560' total_tokens: 1161 total_price: '0.0012890' currency: USD latency: 0.7682376249867957 retriever_resources: - position: 1 dataset_id: 101b4c97-fc2e-463c-90b1-5261a4cdcafb dataset_name: iPhone document_id: 8dd1ad74-0b5f-4175-b735-7d98bbbb4e00 document_name: iPhone List segment_id: ed599c7f-2766-4294-9d1d-e5235a61270a score: 0.98457545 content: >- "Model","Release Date","Display Size","Resolution","Processor","RAM","Storage","Camera","Battery","Operating System" "iPhone 13 Pro Max","September 24, 2021","6.7 inch","1284 x 2778","Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)","6 GB","128, 256, 512 GB, 1TB","12 MP","4352 mAh","iOS 15" created_at: 1705407629 text/event-stream: schema: type: string description: >- 服务器发送事件 (SSE) 流。 **解析**：每个事件是一行以 `data: ` 为前缀的 JSON 对象，以 `\n\n` 终止。解析 JSON 前先去除 `data: ` 前缀，再读取 `event` 字段确定事件类型。忽略 `ping` 事件，它以 `event: ping` 行的形式（无 `data:` 载荷）每 10 秒发送一次以保持连接活跃。 **流生命周期**：工作流进度以 `workflow_started`、节点事件（`node_started` 和 `node_finished`，以及迭代和循环的相应变体）流式返回，回复则以 `message` 事件返回（设置 `reasoning_format: separated` 的 LLM 节点还会同时发送 `reasoning_chunk` 事件，承载模型的推理内容）。结束序列取决于运行结果： - **成功**：`message_end`，随后 `workflow_finished` - **失败**：`workflow_finished`（状态为 `failed`），随后 `error`；不发送 `message_end` - **暂停**：`human_input_required`，随后 `workflow_paused`（流到此结束，运行将另行恢复） 开启文本转语音（TTS）自动播放时，`tts_message_end` 跟随在结束事件之后。 **事件**：除 `ping` 外，每个事件都包含 `conversation_id`、`message_id` 和 `created_at`（Unix 纪元秒）；除 `error` 外，其余事件还包含 `task_id`。工作流、节点和人工介入事件还将载荷嵌套在 `data` 中，且除 `agent_log` 外都带有顶层 `workflow_run_id`。 **回复事件** | 事件 | 触发时机 | 关键字段 | |:---|:---|:---| | `message` | 每个回答片段（按顺序拼接） | `answer` | | `message_replace` | 内容审核替换已生成的回答 | `answer`、`reason` | | `reasoning_chunk` | 每个推理内容增量，当 LLM 节点使用 `reasoning_format: separated` 时（按顺序拼接；`is_final: true` 的事件标志推理结束，且 `reasoning` 可能为空） | `data.message_id`、`data.reasoning`、`data.node_id`、`data.is_final` | | `message_end` | 回答完成 | `metadata`（`usage`、`retriever_resources`） | | `tts_message`、`tts_message_end` | 音频片段/结束，开启 TTS 自动播放时 | `audio` | **工作流与节点事件** 每个事件都将载荷嵌套在 `data` 对象中。 | 事件 | 触发时机 | 关键 `data` 字段 | |:---|:---|:---| | `workflow_started` | 运行开始 | `inputs` | | `node_started` | 节点开始 | `node_id`、`node_type`、`title` | | `node_finished` | 节点结束 | `status`、`outputs`、`execution_metadata` | | `node_retry` | 节点失败后重试 | `retry_index` | | `iteration_started`、`iteration_next`、`iteration_completed` | 迭代节点进度（信息性，可不处理） | `data` | | `loop_started`、`loop_next`、`loop_completed` | 循环节点进度（信息性，可不处理） | `data` | | `agent_log` | Agent 节点步骤日志（信息性，可不处理；无 `workflow_run_id`） | `data` | | `workflow_finished` | 运行结束 | `status`（`succeeded`、`failed`、`partial-succeeded`、`stopped`）、`outputs`、`total_tokens` | | `workflow_paused` | 运行暂停 | `paused_nodes`、`reasons` | | `human_input_required` | 运行到达人工介入节点 | `form_token`、`form_content`、`expiration_time` | 暂停后，本流在 `workflow_paused` 处结束。通过 [提交人工介入表单](/api-reference/人工介入/提交人工介入表单) 提交表单，或等待其超时；恢复后的运行（包括从 `human_input_form_filled`/`human_input_form_timeout` 到 `workflow_finished` 的事件）由 [流式获取工作流事件](/api-reference/对话流/流式获取工作流事件) 流式返回。 **传输事件** | 事件 | 触发时机 | 关键字段 | |:---|:---|:---| | `error` | 失败导致流结束；HTTP 仍为 `200` | `status`（如 `400`）、`code`（如 `invalid_param`）、`message` | | `ping` | 每 10 秒保持连接 | 无 | examples: streamingResponseBasic: summary: Response Example - Streaming (Basic) value: >- data: {"event": "message", "task_id": "mock_task_id", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595} data: {"event": "message_end", "task_id": "mock_task_id", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "created_at": 1679586595, "metadata": {"usage": {"total_tokens": 10, "latency": 1.0}}} streamingResponseWorkflow: summary: Response Example - Streaming (工作流) value: >- data: {"event": "workflow_started", "task_id": "task123", "workflow_run_id": "wfr_abc123", "message_id": "msg123", "conversation_id": "conv123", "created_at": 1705395332, "data": {"id": "wfr_abc123", "workflow_id": "wf_def456", "inputs": {"city": "San Francisco"}, "created_at": 1705395332}} data: {"event": "node_started", "task_id": "task123", "workflow_run_id": "wfr_abc123", "message_id": "msg123", "conversation_id": "conv123", "created_at": 1705395332, "data": {"id": "ne_001", "node_id": "node_llm_1", "node_type": "llm", "title": "LLM", "index": 1, "created_at": 1705395332}} data: {"event": "reasoning_chunk", "task_id": "task123", "message_id": "msg123", "conversation_id": "conv123", "created_at": 1705395333, "data": {"message_id": "msg123", "reasoning": "The user greeted me, so", "node_id": "node_llm_1", "is_final": false}} data: {"event": "reasoning_chunk", "task_id": "task123", "message_id": "msg123", "conversation_id": "conv123", "created_at": 1705395333, "data": {"message_id": "msg123", "reasoning": "", "node_id": "node_llm_1", "is_final": true}} data: {"event": "message", "task_id": "task123", "message_id": "msg123", "conversation_id": "conv123", "answer": " I", "created_at": 1705395333} data: {"event": "node_finished", "task_id": "task123", "workflow_run_id": "wfr_abc123", "message_id": "msg123", "conversation_id": "conv123", "created_at": 1705395334, "data": {"id": "ne_001", "node_id": "node_llm_1", "node_type": "llm", "title": "LLM", "index": 1, "status": "succeeded", "elapsed_time": 1.5, "created_at": 1705395332, "finished_at": 1705395334}} data: {"event": "message_end", "task_id": "task123", "message_id": "msg123", "conversation_id": "conv123", "created_at": 1705395334, "metadata": {"usage": {"total_tokens": 50, "latency": 2.5}}} data: {"event": "workflow_finished", "task_id": "task123", "workflow_run_id": "wfr_abc123", "message_id": "msg123", "conversation_id": "conv123", "created_at": 1705395335, "data": {"id": "wfr_abc123", "workflow_id": "wf_def456", "status": "succeeded", "elapsed_time": 2.5, "total_tokens": 50, "total_steps": 2, "created_at": 1705395332, "finished_at": 1705395335}} humanInputPause: summary: 响应示例 - 人工介入暂停 value: >- data: {"event": "workflow_started", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "message_id": "2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b", "conversation_id": "9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7", "created_at": 1705407629, "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "inputs": {"draft": "Hello"}, "created_at": 1705407629, "reason": "initial"}} data: {"event": "human_input_required", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "message_id": "2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b", "conversation_id": "9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7", "created_at": 1705407629, "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"form_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "form_token": "tok_abc123", "node_id": "approval_node", "node_title": "Approval", "form_content": "Please review the draft.", "inputs": [{"type": "paragraph", "output_variable_name": "comment", "default": null}], "actions": [{"id": "approve", "title": "Approve", "button_style": "primary"}], "display_in_ui": false, "resolved_default_values": {"comment": ""}, "expiration_time": 1705494029}} data: {"event": "workflow_paused", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "message_id": "2e4f6a8b-1c3d-5e7f-9a0b-2c4d6e8f0a1b", "conversation_id": "9d3a2f1b-6c7d-4e8f-a0b1-c2d3e4f5a6b7", "created_at": 1705407629, "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "paused_nodes": ["approval_node"], "outputs": {}, "reasons": [{"TYPE": "human_input_required", "form_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "form_content": "Please review the draft.", "inputs": [{"type": "paragraph", "output_variable_name": "comment", "default": null}], "actions": [{"id": "approve", "title": "Approve", "button_style": "primary"}], "node_id": "approval_node", "node_title": "Approval", "resolved_default_values": {"comment": ""}, "form_token": "tok_abc123", "expiration_time": 1705494029}], "status": "paused", "created_at": 1705407629, "elapsed_time": 0.5, "total_tokens": 0, "total_steps": 1}} '400': description: |- - `app_unavailable` : 应用不可用或配置错误。 - `not_chat_app` : App mode does not match the API route. - `conversation_completed` : The conversation has ended. - `provider_not_initialize` : 未找到有效的模型提供商凭据。 - `provider_quota_exceeded` : 模型提供商配额已用尽。 - `model_currently_not_support` : 当前模型不可用。 - `completion_request_error` : 文本生成失败。 - `bad_request` : Cannot use draft 工作流 version. - `bad_request` : Invalid `workflow_id` format. content: application/json: examples: app_unavailable: summary: app_unavailable value: status: 400 code: app_unavailable message: App unavailable, please check your app configurations. not_chat_app: summary: not_chat_app value: status: 400 code: not_chat_app message: Please check if your app mode matches the right API route. conversation_completed: summary: conversation_completed value: status: 400 code: conversation_completed message: >- The conversation has ended. Please start a new conversation. provider_not_initialize: summary: provider_not_initialize value: status: 400 code: provider_not_initialize message: >- No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. provider_quota_exceeded: summary: provider_quota_exceeded value: status: 400 code: provider_quota_exceeded message: >- Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials. model_currently_not_support: summary: model_currently_not_support value: status: 400 code: model_currently_not_support message: >- Dify Hosted OpenAI trial currently not support the GPT-4 model. completion_request_error: summary: completion_request_error value: status: 400 code: completion_request_error message: Completion request failed. is_draft_workflow: summary: bad_request value: status: 400 code: bad_request message: >- Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab. workflow_id_format_error: summary: bad_request value: status: 400 code: bad_request message: 'Invalid workflow_id format: ''not-a-valid-id''. ' '404': description: |- - `not_found` : Conversation does not exist. - `not_found` : 工作流 not found with the specified `workflow_id`. content: application/json: examples: conversation_not_exists: summary: not_found value: status: 404 code: not_found message: Conversation Not Exists. workflow_not_found: summary: not_found value: status: 404 code: not_found message: >- Workflow not found with id: a1b2c3d4-5678-90ab-cdef-1234567890ab '429': description: |- - `too_many_requests` : 该应用的并发请求过多。 - `rate_limit_error` : 上游模型提供商的速率限制已超出。 content: application/json: examples: too_many_requests: summary: too_many_requests value: status: 429 code: too_many_requests message: Too many requests. Please try again later. rate_limit_error: summary: rate_limit_error value: status: 429 code: rate_limit_error message: Rate Limit Error '500': description: '`internal_server_error` : 内部服务器错误。' content: application/json: examples: internal_server_error: summary: internal_server_error value: status: 500 code: internal_server_error message: Internal server error. components: schemas: ChatRequest: type: object required: - inputs - query - user properties: query: type: string description: 用户输入/问题内容。 inputs: type: object description: >- 允许输入应用定义的各种变量值。包含键值对。请参阅 [获取应用参数](/api-reference/应用配置/获取应用参数) 响应中的 `user_input_form` 字段，以了解应用所需的变量名称和类型。 additionalProperties: true response_mode: type: string enum: - streaming - blocking description: >- 响应返回模式。`streaming`（推荐）使用 SSE。`blocking` 等待完成后返回（长时间处理可能会被中断）。Cloudflare 超时为 `100 s`。省略时默认为阻塞模式。 user: type: string description: 用户标识符，在应用内唯一。此标识符用于限定数据访问范围——会话、消息和文件仅在使用相同的 `user` 值查询时可见。 conversation_id: type: string description: >- 用于继续会话的会话 ID。传入上一条消息的 `conversation_id`。要开始新会话，请省略此字段或传入空字符串。响应会返回一个 `conversation_id`——在后续消息中传入该值即可继续该会话。 files: type: array description: >- 用于多模态理解的文件列表，包括图片、文档、音频和视频。要附加本地文件，请先通过 [上传文件](/api-reference/文件操作/上传文件) 上传，然后将返回的 `id` 作为 `upload_file_id`，并设置 `transfer_method: local_file`。 items: type: object required: - type - transfer_method properties: type: type: string enum: - image - document - audio - video - custom description: 文件类型。 transfer_method: type: string enum: - remote_url - local_file description: 传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。 url: type: string format: url description: 文件 URL（当 `transfer_method` 为 `remote_url` 时必填）。 upload_file_id: type: string description: >- 通过 [上传文件](/api-reference/文件操作/上传文件) API 获取的已上传文件 ID（当 `transfer_method` 为 `local_file` 时必填）。 auto_generate_name: type: boolean description: >- 自动生成会话标题。如果为 `false`，请使用 [重命名会话](/api-reference/会话管理/重命名会话) API 并设置 `auto_generate: true` 来异步生成标题。 default: true workflow_id: type: string description: 指定要执行的已发布工作流版本 ID。如果未提供，将使用最新发布的版本。 ChatCompletionResponse: type: object properties: event: type: string description: 事件类型，固定为 `message`。 task_id: type: string format: uuid description: 用于请求追踪和停止响应 API 的任务 ID。 id: type: string format: uuid description: 该响应事件的唯一 ID。 message_id: type: string format: uuid description: 唯一的消息 ID。调用反馈或推荐问题接口时，将此值作为 `message_id` 参数使用。 conversation_id: type: string format: uuid description: 会话 ID。 mode: type: string description: 应用模式，固定为 `advanced-chat`。 answer: type: string description: 完整的响应内容。 metadata: type: object description: 包含用量和检索资源的元数据。 properties: usage: $ref: '#/components/schemas/Usage' retriever_resources: type: array description: 使用的检索资源列表。 items: $ref: '#/components/schemas/RetrieverResource' created_at: type: integer format: int64 description: 消息创建时间戳（Unix 纪元秒）。 Usage: type: object description: 模型使用信息。 properties: prompt_tokens: type: integer description: 提示词中的令牌数。 prompt_unit_price: type: string format: decimal description: 每个提示词令牌的单价。 prompt_price_unit: type: string format: decimal description: 提示词令牌的价格单位。 prompt_price: type: string format: decimal description: 提示词令牌的总价。 completion_tokens: type: integer description: 补全内容中的令牌数。 completion_unit_price: type: string format: decimal description: 每个补全令牌的单价。 completion_price_unit: type: string format: decimal description: 补全令牌的价格单位。 completion_price: type: string format: decimal description: 补全令牌的总价。 total_tokens: type: integer description: 使用的令牌总数。 total_price: type: string format: decimal description: 所有令牌的总价。 currency: type: string description: 计价货币。 latency: type: number format: double description: 延迟时间（秒）。 RetrieverResource: type: object description: 检索资源的引用和归属信息。 properties: id: type: string format: uuid description: 检索资源的唯一 ID。 message_id: type: string format: uuid description: 该资源所属消息的 ID。 position: type: integer description: 资源在列表中的位置。 dataset_id: type: string format: uuid description: 知识库 ID。 dataset_name: type: string description: 知识库名称。 document_id: type: string format: uuid description: 文档 ID。 document_name: type: string description: 文档名称。 data_source_type: type: string description: 数据源类型。 segment_id: type: string format: uuid description: 文档中特定块的 ID。 score: type: number format: float description: 资源的相关性评分。 hit_count: type: integer description: 该块被命中的次数。 word_count: type: integer description: 块的字数。 segment_position: type: integer description: 块在文档中的位置。 index_node_hash: type: string description: 索引节点的哈希值。 content: type: string description: 资源的内容片段。 summary: type: string nullable: true description: 块内容的摘要。 created_at: type: integer format: int64 description: 创建时间戳（Unix 纪元秒）。 securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- API Key 认证。对于所有 API 请求，请在 `Authorization` HTTP 头中包含您的 API Key，并加上 `Bearer ` 前缀。示例：`Authorization: Bearer {API_KEY}`。**强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。** ````