> ## Documentation Index > Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # 发送对话消息 > **适用于**：Chatflow。 向已部署的 Chatflow 应用发送消息并返回回答，支持阻塞和流式两种模式。 **对应的标准 API 接口**：[发送对话消息](/zh/3.13.x/develop/api/chat-messages/send-chat-message)。差异： - 忽略 `workflow_id` 和 `auto_generate_name`。 - 接受 `trace_id` 和 `trace_session_id`。 - 流中不包含 TTS、内容审查、标注和 Agent 事件。 - 错误码不同。 ## OpenAPI ````yaml /zh/3.13.x/develop/api/openapi_service.json post /v2/chat-messages openapi: 3.0.1 info: title: Dify 服务 API description: 用于 Dify 应用与知识库的 REST API。应用类接口使用应用 API 密钥认证，知识库类接口使用知识库 API 密钥认证。 version: 1.0.0 servers: - url: https://{api_base_url} description: Dify 服务 API 的基础 URL。替换为你部署的 API 基础 URL。 variables: api_base_url: default: api.example.com/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: 暂停等待人工输入的工作流恢复操作。 - name: 工作流运行 description: 用于执行和管理工作流的操作。 - name: 文本生成消息 description: 文本生成相关操作。 - name: 知识库 description: 用于管理知识库的操作，包括创建、配置和检索。 - name: 文档 description: 用于在知识库中创建、更新和管理文档的操作。 - name: 分段 description: 用于管理分段和子分段的操作。 - name: 元数据 description: 用于管理知识库元数据字段和文档元数据值的操作。 - name: 标签 description: 用于管理知识库标签和标签绑定的操作。 - name: 模型 description: 用于获取可用模型的操作。 - name: 知识流水线 description: 用于管理和运行知识流水线的操作，包括数据源插件和流水线执行。 - name: 部署环境 description: >- 部署环境通过 `v2` 基础 URL 提供的接口。部署环境只提供本组中的接口，调用其他路径会返回 `404 not_found`。认证方式和错误码与标准服务 API 不同，部署环境以本组页面为准。 paths: /v2/chat-messages: post: tags: - 部署环境 summary: 发送对话消息 description: >- **适用于**：Chatflow。 向已部署的 Chatflow 应用发送消息并返回回答，支持阻塞和流式两种模式。 **对应的标准 API 接口**：[发送对话消息](/zh/3.13.x/develop/api/chat-messages/send-chat-message)。差异： - 忽略 `workflow_id` 和 `auto_generate_name`。 - 接受 `trace_id` 和 `trace_session_id`。 - 流中不包含 TTS、内容审查、标注和 Agent 事件。 - 错误码不同。 operationId: sendDeployedChatMessageCn parameters: - name: X-Trace-Id in: header required: false schema: type: string description: 与请求体字段 `trace_id` 相同，优先读取。 - name: trace_id in: query required: false schema: type: string description: 与请求体字段 `trace_id` 相同，在请求头之后读取。 - name: X-Trace-Session-Id in: header required: false schema: type: string description: 与请求体字段 `trace_session_id` 相同，优先读取。 - name: trace_session_id in: query required: false schema: type: string description: 与请求体字段 `trace_session_id` 相同，在请求头之后读取。 requestBody: description: 发送对话消息的请求体。 required: true content: application/json: schema: type: object required: - query - inputs - user properties: query: type: string description: 用户发送的消息。 inputs: type: object description: |- 应用输入变量的值，以变量名为键。请按照目标环境当前部署版本中定义的输入变量传值。 单文件变量传入一个文件对象，文件列表变量传入文件对象数组；文件对象的结构与 `files` 中的条目相同。 additionalProperties: true response_mode: type: string enum: - streaming - blocking description: |- 指定响应如何返回。 - `streaming`：运行每产出一个事件就立即返回，适合快速回复以外的所有场景。 - `blocking`：运行结束后一次性返回一个响应。 default: blocking user: type: string description: >- 终端用户标识，由你的应用定义，需在应用内唯一。会话、消息和文件仅对携带相同 `user` 的请求可见。参见 [终端用户身份](/zh/3.13.x/develop/api/guides/end-user-identity)。 conversation_id: type: string description: >- 要继续的会话 ID。省略或传空字符串则开启新会话，响应会返回 `conversation_id`，供下一条消息使用。要接着此前的会话继续，可从 [获取会话列表](/zh/3.13.x/develop/api/deployed-environments/list-conversations) 取得它的 ID。 files: type: array description: >- 随消息附带的文件。本地文件需先通过 [上传文件](/zh/3.13.x/develop/api/deployed-environments/upload-file) 上传，再把返回的 `id` 作为 `upload_file_id` 引用，并设置 `transfer_method: local_file`。 items: type: object required: - type properties: type: type: string enum: - image - document - audio - video - custom description: 文件类型。上传文件的类型必须与 Dify 存储该文件时识别出的类型一致，声明为 `custom` 时除外。 transfer_method: type: string enum: - remote_url - local_file description: >- 传输方式：文件 URL 使用 `remote_url`，上传文件使用 `local_file`。条目缺少该字段时直接忽略，不会报错。 url: type: string format: url description: '`remote_url` 条目的文件 URL。' upload_file_id: type: string description: >- [上传文件](/zh/3.13.x/develop/api/deployed-environments/upload-file) 返回的 `id`。当 `transfer_method` 为 `local_file` 时必填。 trace_id: type: string description: 追踪标识，会传递到可观测性数据中。可使用字母、数字、连字符和下划线，最长 128 个字符。不符合的值直接跳过，不会报错。 trace_session_id: type: string description: 追踪会话标识，会传递到可观测性数据中，去除首尾空白后长度为 1 到 200 个字符。 minLength: 1 maxLength: 200 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: type: object properties: event: type: string description: 固定为 `message`。 task_id: type: string description: >- 本次运行的任务 ID。使用阻塞式返回时，它只出现在最终响应体中，因此 [停止响应](/zh/3.13.x/develop/api/deployed-environments/stop-chat-message-generation) 实际只在流式返回时可用。 id: type: string description: 消息 ID。 message_id: type: string description: 消息 ID，与 `id` 取值相同。 conversation_id: type: string description: 本轮对话所属的会话；省略 `conversation_id` 时，返回新建会话的 ID。 mode: type: string description: 固定为 `advanced-chat`。 answer: type: string description: 完整的回答文本。 metadata: type: object description: 运行元数据，其中 `usage` 包含 token 数量、费用和延迟。 additionalProperties: true created_at: type: integer description: 运行开始时间，Unix 时间戳（秒）。 examples: blocking: summary: 响应示例 - 阻塞式返回 value: event: message task_id: b4f9d1c2-5c1a-4b3e-9f0e-2a6d8c7e5f01 id: 7c9e6679-7425-40de-944b-e07fc1f90ae7 message_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7 conversation_id: 0f8fad5b-d9cb-469f-a165-70867728950e mode: advanced-chat answer: Your refund is being processed by the bank. metadata: usage: prompt_tokens: 28 completion_tokens: 19 total_tokens: 47 currency: USD latency: 0.42 created_at: 1787788860 text/event-stream: examples: streaming: summary: 响应示例 - 流式返回 value: >+ event: ping data: {"event": "workflow_started", "task_id": "b4f9d1c2-5c1a-4b3e-9f0e-2a6d8c7e5f01", "conversation_id": "0f8fad5b-d9cb-469f-a165-70867728950e", "message_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "created_at": 1787788860, "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "inputs": {"city": "San Francisco", "sys.query": "What are the specs of the iPhone 13 Pro Max?", "sys.user_id": "abc-123"}, "created_at": 1787788860, "reason": "initial"}} data: {"event": "message", "task_id": "b4f9d1c2-5c1a-4b3e-9f0e-2a6d8c7e5f01", "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "conversation_id": "0f8fad5b-d9cb-469f-a165-70867728950e", "message_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "created_at": 1787788860, "answer": "Your refund is being processed", "from_variable_selector": ["llm", "text"]} data: {"event": "message_end", "task_id": "b4f9d1c2-5c1a-4b3e-9f0e-2a6d8c7e5f01", "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "conversation_id": "0f8fad5b-d9cb-469f-a165-70867728950e", "message_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "created_at": 1787788860, "metadata": {"usage": {"prompt_tokens": 28, "completion_tokens": 19, "total_tokens": 47, "currency": "USD", "latency": 0.42}}, "files": []} data: {"event": "workflow_finished", "task_id": "b4f9d1c2-5c1a-4b3e-9f0e-2a6d8c7e5f01", "conversation_id": "0f8fad5b-d9cb-469f-a165-70867728950e", "message_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "created_at": 1787788860, "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "status": "succeeded", "outputs": {"answer": "Your refund is being processed by the bank."}, "error": null, "elapsed_time": 1.8, "total_tokens": 47, "total_steps": 3, "created_by": {"id": "5c3b1f0a-9d2e-5a7b-8c4d-6e1f2a3b4c5d", "user": "abc-123"}, "created_at": 1787788860, "finished_at": 1787788862, "exceptions_count": 0, "files": []}} schema: type: string description: >- Server-Sent Events（SSE）流。按 [SSE 流式传输指南](/zh/3.13.x/develop/api/guides/streaming) 解析。 **事件**：先发送 `workflow_started`。随后是节点事件 `node_started`、`node_finished`、`node_retry`，以及迭代和循环的相应变体。`message` 片段与这些事件交替到达。把 `message` 片段按顺序拼接即可得到回答。 结尾的帧取决于运行结果： - 成功、部分成功或停止：先 `message_end`，再 `workflow_finished`。 - 工作流失败：只发送 `workflow_finished`，状态为 `failed`，失败原因在 `data.error` 中；不发送 `message_end`。 - 流打开后才发现的失败，例如超时、因部署变更而取消、内部错误：先收到一个 `error` 帧，流随即结束。 流打开前发生的失败，即使在流式模式下也会返回普通的 HTTP 错误响应。500 `execution_failed` 和 504 `request_timeout` 只可能在流打开之后发生。因此在流式模式下，它们只以 `error` 帧的形式到达，不会作为 HTTP 状态码返回。 **附加事件**：`ping` 帧不携带数据。流开始时发送一次，之后约每 10 秒一次，输出过程中也会出现。模型输出推理内容时，由 `reasoning_chunk` 增量承载。 **通用字段**：除 `ping` 和 `error` 外，每个事件都包含 `conversation_id`、`message_id`、`task_id` 和 `created_at`。工作流事件和节点事件还带有 `workflow_run_id`，`message` 和 `message_end` 帧则没有。`message_end.metadata` 只带有 `usage`。 **`error` 帧**：每个 `error` 帧都带有 `conversation_id`、`message_id`、`created_at`，以及 `code`、`status` 和 `message`。运行结束但没有返回结果时，`error` 帧用 `workflow_run_id` 代替 `conversation_id`、`message_id` 和 `created_at`。 '400': description: >- - `invalid_param`：缺少 `query`、`inputs` 或 `user`。`message` 依次为 `query is required`、`inputs is required` 和 `user is required`。 - `invalid_param`：`conversation_id` 不是有效的会话 ID。`message` 为 `conversation_id is invalid`。 - `invalid_param`：`response_mode` 既不是 `blocking` 也不是 `streaming`。`message` 为 `response_mode must be blocking or streaming`。 - `invalid_param`：`trace_session_id` 的类型或长度不符合要求。`message` 为 `trace_session_id must be a string` 或 `trace_session_id must be 1 to 200 characters after trimming`。 - `invalid_param`（消息以 `Run failed:` 开头）：阻塞式返回时工作流执行失败。消息的其余部分是本次运行自身的错误文本。重试前先修正工作流或其输入。 - `invalid_request`：请求体解析失败。`message` 为 `invalid request body`。 - `invalid_request`：该 API 密钥所属的应用不是 Chatflow。`message` 为 `run route does not match the deployed app mode`。 - `invalid_request`：某个文件条目未通过校验。`message` 会指出具体原因，例如 `unsupported file type`、`too many files`、`invalid upload_file_id`、`file input takes a single file` 或 `file list input takes a list of files`。 - `invalid_request`：请求体被判定为过大。`message` 为 `request payload is too large`。 - `invalid_request`：`user` 长度为 256 至 512 字节，或包含 NUL 字符。`message` 为 `chat turn is invalid`。 - `invalid_request`：`user` 首尾带有空白字符。`message` 为 `workflow run identity is invalid`。 content: application/json: examples: invalid_param: summary: invalid_param value: code: invalid_param message: inputs is required status: 400 run_failed: summary: invalid_param（运行失败） value: code: invalid_param message: >- Run failed: [OpenAI] Error: Rate limit reached for requests status: 400 invalid_request: summary: invalid_request value: code: invalid_request message: run route does not match the deployed app mode status: 400 '401': description: >- - `token_invalid`：API 密钥缺失、格式错误或无法识别。 - `unauthorized`：API 密钥已撤销。 - `runtime_identity_invalid`：请求携带的身份签名在本次运行获准前已过期，上传较慢时容易出现。重新发起请求即可。 content: application/json: examples: token_invalid: summary: token_invalid value: code: token_invalid message: invalid api token status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 runtime_identity_invalid: summary: runtime_identity_invalid value: code: runtime_identity_invalid message: runtime identity is invalid status: 401 '403': description: '`forbidden`：该应用在 **访问点** 中关闭了 API 访问。' content: application/json: examples: forbidden: summary: forbidden value: code: forbidden message: The app's API service has been disabled. status: 403 '404': description: >- `not_found`：会话或 `upload_file_id` 指向的文件不存在，或者属于其他 `user`。两种情况都返回 `conversation was not found`。 content: application/json: examples: not_found: summary: not_found value: code: not_found message: conversation was not found status: 404 '409': description: >- - `request_canceled`：运行开始后收到停止请求，但未能及时正常结束。其他情况下，停止运行不会返回此错误，流式返回会以 `status: stopped` 的 `workflow_finished` 事件结束。 - `request_canceled`：运行过程中部署发生变更，本次运行随之取消。改用当前部署重试。 content: application/json: examples: request_canceled_mid_run: summary: request_canceled（已停止） value: code: request_canceled message: request canceled status: 409 request_canceled_deployment_changed: summary: request_canceled（部署已变更） value: code: request_canceled message: deployment changed; retry against the current deployment status: 409 '413': description: >- `request_too_large`：请求体超过 8 MiB。运行过程中还会再检查一次请求体大小，返回的消息相同，但状态码是 400，错误码是 `invalid_request`。 content: application/json: examples: request_too_large: summary: request_too_large value: code: request_too_large message: request payload is too large status: 413 '429': description: '`queue_full`：该环境的运行队列已满，退避后重试。' content: application/json: examples: queue_full: summary: queue_full value: code: queue_full message: worker queue is full status: 429 '500': description: >- - `execution_failed`：本次运行在工作流产出结果前失败。先在 **调用记录** 中查看这次运行，修正工作流后再重试。 - `internal_error`：环境出现与请求内容无关的错误。可重试，若持续出现则联系管理员。 - `internal_error`：使用阻塞式返回时，运行结束但没有返回结果。可重试，若持续出现则联系管理员。 - `internal_server_error`：运行已结束，但回复没能记录下来，因此没有返回任何内容。重新发送这条消息，若持续出现则联系管理员。 - `internal_server_error`：使用流式返回时，运行结束但没有返回结果。该错误作为流中的 `error` 事件返回，`status` 为 500。可重试，若持续出现则联系管理员。 content: application/json: examples: execution_failed: summary: execution_failed value: code: execution_failed message: workflow execution failed status: 500 internal_error: summary: internal_error value: code: internal_error message: internal error status: 500 internal_server_error: summary: internal_server_error value: code: internal_server_error message: Internal Server Error, please contact support. status: 500 '503': description: >- - `deployment_undeployed`：该应用已从此环境下线。 - `deployment_not_ready`：部署正在进行中，稍后重试。 - `apprunner_not_deployed`：该环境不可用，例如环境正在删除。 - `enterprise_unavailable`：平台侧的路由服务暂时不可用，稍后重试。 - `service_not_ready`：已部署的版本尚未在该环境中就绪，稍后重试。 - `service_not_ready`：`user` 超过 512 字节，或本次请求引用的不同文件超过 100 个。`message` 为 `conversation service is temporarily unavailable`。重试无效，需将 `user` 缩短到少于 256 字节，或减少文件数量。 content: application/json: examples: deployment_undeployed: summary: deployment_undeployed value: code: deployment_undeployed message: deployment is not deployed status: 503 deployment_not_ready: summary: deployment_not_ready value: code: deployment_not_ready message: deployment is in progress status: 503 apprunner_not_deployed: summary: apprunner_not_deployed value: code: apprunner_not_deployed message: apprunner not deployed for this environment status: 503 enterprise_unavailable: summary: enterprise_unavailable value: code: enterprise_unavailable message: enterprise routing service unavailable status: 503 service_not_ready: summary: service_not_ready value: code: service_not_ready message: revision is not serving status: 503 service_not_ready_admission: summary: service_not_ready（请求超限） value: code: service_not_ready message: conversation service is temporarily unavailable status: 503 '504': description: '`request_timeout`：本次运行超过平台为工作流运行设定的最长执行时间，已被停止。该上限由平台管理员设置。' content: application/json: examples: request_timeout: summary: request_timeout value: code: request_timeout message: request timed out status: 504 servers: - url: https://{deployed_api_base_url} description: 所有部署环境共用的基础 URL，即把标准服务 API 地址中的 `/v1` 换成 `/v2`。 variables: deployed_api_base_url: default: api.example.com description: >- 打开应用的 **访问点** 标签页，从任一部署环境的 **后端服务 API** 卡片复制完整 URL，再去掉开头的 `https://` 和末尾的 `/v2`。 components: securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- 每个请求都通过 API Key 认证：`Authorization: Bearer {API_KEY}`。应用接口使用应用 API Key，知识库接口使用知识库 API Key（[快速开始](/zh/3.13.x/develop/api/guides/get-started)）。 API Key 应保存在服务端，切勿嵌入客户端代码。缺失或无效的 Key 会返回 HTTP `401`（`unauthorized`）。 ````