> ## 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. # Send Chat Message > **Available for**: Chatflow Sends a message to a deployed Chatflow app and returns the answer, in blocking or streaming mode. **Standard API equivalent**: [Send Chat Message](/en/3.13.x/develop/api/chat-messages/send-chat-message). Differences: - `workflow_id` and `auto_generate_name` are ignored. - `trace_id` and `trace_session_id` are accepted. - The stream omits TTS, moderation, annotation, and agent events. - Error codes differ. ## OpenAPI ````yaml /en/3.13.x/develop/api/openapi_service.json post /v2/chat-messages openapi: 3.0.1 info: title: Dify Service API description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. version: 1.0.0 servers: - url: https://{api_base_url} description: >- Base URL of the Dify Service API. Replace it with your deployment's API endpoint. variables: api_base_url: default: api.example.com/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - name: Chat Messages description: Operations related to chat messages and interactions. - name: Files description: File upload and preview operations. - name: End Users description: Operations related to end user information. - name: Feedback description: User feedback operations. - name: Conversations description: Operations related to managing conversations. - name: Audio description: Text-to-Speech and Speech-to-Text operations. - name: Applications description: Operations to retrieve application settings and information. - name: Annotations description: Operations related to managing annotations for direct replies. - name: Human Input description: Endpoints for resuming paused workflows that require human input. - name: Workflow Runs description: Operations for executing and managing workflows. - name: Completion Messages description: Operations related to text generation and completion. - name: Knowledge Bases description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. - name: Documents description: >- Operations for creating, updating, and managing documents within a knowledge base. - name: Chunks description: Operations for managing document chunks and child chunks. - name: Metadata description: >- Operations for managing knowledge base metadata fields and document metadata values. - name: Tags description: Operations for managing knowledge base tags and tag bindings. - name: Models description: Operations for retrieving available models. - name: Knowledge Pipeline description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. - name: Deployed Environments description: >- Endpoints served by deployed environments over the `v2` base URL. Deployed environments serve only the endpoints in this group; calling any other path there returns `404 not_found`. Authentication and errors differ from the standard Service API; each page here is authoritative for deployed environments. paths: /v2/chat-messages: post: tags: - Deployed Environments summary: Send Chat Message description: >- **Available for**: Chatflow Sends a message to a deployed Chatflow app and returns the answer, in blocking or streaming mode. **Standard API equivalent**: [Send Chat Message](/en/3.13.x/develop/api/chat-messages/send-chat-message). Differences: - `workflow_id` and `auto_generate_name` are ignored. - `trace_id` and `trace_session_id` are accepted. - The stream omits TTS, moderation, annotation, and agent events. - Error codes differ. operationId: sendDeployedChatMessage parameters: - name: X-Trace-Id in: header required: false schema: type: string description: Same as the `trace_id` body field, checked first. - name: trace_id in: query required: false schema: type: string description: Same as the `trace_id` body field, checked after the header. - name: X-Trace-Session-Id in: header required: false schema: type: string description: Same as the `trace_session_id` body field, checked first. - name: trace_session_id in: query required: false schema: type: string description: Same as the `trace_session_id` body field, checked after the header. requestBody: description: Request body to send a chat message. required: true content: application/json: schema: type: object required: - query - inputs - user properties: query: type: string description: The user's message. inputs: type: object description: >- Values for the app's input variables, keyed by variable name. Use the input variables defined in the version currently deployed to the target environment. Pass a file object for a single-file variable, or an array of file objects for a file-list variable. Each file object has the same structure as an item in `files`. additionalProperties: true response_mode: type: string enum: - streaming - blocking description: >- How the response is delivered. - `streaming`: events arrive as the run produces them. Use it for anything longer than a quick reply. - `blocking`: one response once the run completes. default: blocking user: type: string description: >- End-user identifier, defined by your app and unique within it. Conversations, messages, and files are visible only to requests carrying the same `user`. See [End User Identity](/en/3.13.x/develop/api/guides/end-user-identity). conversation_id: type: string description: >- ID of the conversation to continue. Omit it or pass an empty string to start a new conversation; the response returns a `conversation_id` to send with the next message. To resume an earlier conversation, get its ID from [List Conversations](/en/3.13.x/develop/api/deployed-environments/list-conversations). files: type: array description: >- Files to attach to the message. For a local file, first upload it via [Upload File](/en/3.13.x/develop/api/deployed-environments/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`. items: type: object required: - type properties: type: type: string enum: - image - document - audio - video - custom description: >- File type. For an uploaded file it must match the type Dify detected when the file was stored, unless you declare `custom`. transfer_method: type: string enum: - remote_url - local_file description: >- Transfer method: `remote_url` for a file URL, `local_file` for an uploaded file. An entry that omits this field is ignored rather than rejected. url: type: string format: url description: File URL for a `remote_url` entry. upload_file_id: type: string description: >- The `id` from [Upload File](/en/3.13.x/develop/api/deployed-environments/upload-file). Required when `transfer_method` is `local_file`. trace_id: type: string description: >- Trace identifier propagated to observability data. Letters, digits, hyphens, and underscores are accepted, up to 128 characters. A value that does not match is skipped, not rejected. trace_session_id: type: string description: >- Trace session identifier propagated to observability data, 1 to 200 characters after trimming. minLength: 1 maxLength: 200 examples: streaming_example: summary: Request Example - Streaming mode 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: Request Example - Blocking mode 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: >- The content type and structure depend on the `response_mode` parameter in the request. - If `response_mode` is `blocking`, returns `application/json` with a `ChatCompletionResponse` object. - If `response_mode` is `streaming`, returns `text/event-stream` with a stream of Server-Sent Events. content: application/json: schema: type: object properties: event: type: string description: Always `message`. task_id: type: string description: >- Task ID for this run. In blocking mode it arrives only in this final body, so [Stop Chat Message Generation](/en/3.13.x/develop/api/deployed-environments/stop-chat-message-generation) is practical only with streaming. id: type: string description: Message ID. message_id: type: string description: Message ID (same value as `id`). conversation_id: type: string description: >- Conversation the turn belongs to; a new conversation's ID when `conversation_id` was omitted. mode: type: string description: Always `advanced-chat`. answer: type: string description: The complete answer text. metadata: type: object description: >- Run metadata; contains `usage` with token counts, prices, and latency. additionalProperties: true created_at: type: integer description: Run start time as a Unix timestamp in seconds. examples: blocking: summary: Response Example - Blocking mode 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: Response Example - Streaming mode 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; parse them per [SSE Streaming](/en/3.13.x/develop/api/guides/streaming). **Events**: `workflow_started` comes first. The node events follow: `node_started`, `node_finished`, `node_retry`, and the iteration and loop variants. `message` chunks arrive alongside them. Concatenate the `message` chunks in order to build the answer. The closing frames depend on the outcome: - Success, partial success, or a stop: `message_end`, then `workflow_finished`. - Workflow failure: `workflow_finished` alone, with `status: failed` and the reason in `data.error`; no `message_end`. - A failure discovered after the stream opened, such as a timeout, a cancel because the deployment changed, or an internal error: an `error` frame, then the stream ends. A failure raised before the stream opened returns an ordinary HTTP error response even in streaming mode. 500 `execution_failed` and 504 `request_timeout` can only occur after the stream has opened. In streaming mode they therefore arrive as `error` frames, never as HTTP statuses. **Add-ons**: `ping` frames carry no data. One arrives when the stream opens, and another about every 10 s, including mid-output. When the model emits reasoning, `reasoning_chunk` deltas carry it. **Common fields**: apart from `ping` and `error`, every event includes `conversation_id`, `message_id`, `task_id`, and `created_at`. The workflow and node events also carry `workflow_run_id`; `message` and `message_end` frames do not. `message_end.metadata` carries `usage` only. **`error` frames**: each carries `conversation_id`, `message_id`, and `created_at` alongside `code`, `status`, and `message`. A frame for a run that ended without a result carries `workflow_run_id` in place of `conversation_id`, `message_id`, and `created_at`. '400': description: >- - `invalid_param`: `query`, `inputs`, or `user` is missing. Messages `query is required`, `inputs is required`, and `user is required`. - `invalid_param`: `conversation_id` is not a valid conversation ID. Message `conversation_id is invalid`. - `invalid_param`: `response_mode` is neither `blocking` nor `streaming`. Message `response_mode must be blocking or streaming`. - `invalid_param`: `trace_session_id` is the wrong type or the wrong length. Messages `trace_session_id must be a string` and `trace_session_id must be 1 to 200 characters after trimming`. - `invalid_param` with a message starting `Run failed:`: in blocking mode, the workflow finished with a failure. The rest of the message is the run's own error text. Fix the workflow or its inputs before retrying. - `invalid_request`: the body could not be parsed. Message `invalid request body`. - `invalid_request`: the API key belongs to an app that is not a Chatflow. Message `run route does not match the deployed app mode`. - `invalid_request`: a file entry failed validation. The message names the problem, for example `unsupported file type`, `too many files`, `invalid upload_file_id`, `file input takes a single file`, or `file list input takes a list of files`. - `invalid_request`: the body was rejected as too large. Message `request payload is too large`. - `invalid_request`: `user` is 256 to 512 bytes long or contains a NUL character. Message `chat turn is invalid`. - `invalid_request`: `user` starts or ends with whitespace. 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 (run failed) 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`: the API key is missing, malformed, or unknown. - `unauthorized`: the API key has been revoked. - `runtime_identity_invalid`: the request's signed identity expired before the run was admitted. A slow upload can take long enough for that, so send the request again. 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`: the app''s API access is turned off in **Access Point**.' 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`: the conversation, or a file named by `upload_file_id`, does not exist or belongs to another `user`. Both cases report `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`: a stop arrived after the run started, and the run didn't end cleanly in time. Otherwise, a stop ends the stream with a `workflow_finished` event with `status: stopped` instead of this error. - `request_canceled`: the deployment changed while the run was in flight, so the run was canceled. Retry against the current deployment. content: application/json: examples: request_canceled_mid_run: summary: request_canceled (stopped) value: code: request_canceled message: request canceled status: 409 request_canceled_deployment_changed: summary: request_canceled (deployment changed) value: code: request_canceled message: deployment changed; retry against the current deployment status: 409 '413': description: >- `request_too_large`: the request body exceeds 8 MiB. A second size check later in the run reports the same message as a 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`: the environment's run queue is full; retry with backoff. content: application/json: examples: queue_full: summary: queue_full value: code: queue_full message: worker queue is full status: 429 '500': description: >- - `execution_failed`: the run failed before the workflow produced a result. Check the run in **Invocation Logs** and fix the workflow before retrying. - `internal_error`: the environment hit an error unrelated to your request; retry, and contact your administrator if it persists. - `internal_error`: in blocking mode, the run ended without a result. Retry, and contact your administrator if it persists. - `internal_server_error`: the run finished but its reply could not be recorded, so nothing was returned. Send the message again; contact your administrator if it persists. - `internal_server_error`: in streaming mode, the run ended without a result. It arrives in the stream as an `error` event with `status: 500`. Retry, and contact your administrator if it persists. 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`: the app is undeployed from this environment. - `deployment_not_ready`: a deployment is in progress; retry shortly. - `apprunner_not_deployed`: the environment is not available, for example while it is being deleted. - `enterprise_unavailable`: a platform-side routing service is temporarily unavailable; retry shortly. - `service_not_ready`: the deployed version isn't ready to serve in this environment; retry shortly. - `service_not_ready`: `user` is longer than 512 bytes, or the request references more than 100 different files. Message `conversation service is temporarily unavailable`. Retrying doesn't help: shorten `user` to under 256 bytes, or send fewer files. 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 (oversized request) value: code: service_not_ready message: conversation service is temporarily unavailable status: 503 '504': description: >- `request_timeout`: the run exceeded the platform's maximum execution time for a workflow run and was stopped. Your platform's administrators set this limit. 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: >- Base URL shared by every deployed environment: the standard Service API address, with `/v2` in place of `/v1`. variables: deployed_api_base_url: default: api.example.com description: >- On the app's **Access Point** tab, copy the full URL from any deployed environment's **Backend Service API** card, then remove the `https://` prefix and the trailing `/v2`. components: securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/3.13.x/develop/api/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). ````