> ## 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. # Send Chat Message > Send a request to the chat application. ## OpenAPI ````yaml /en/api-reference/openapi_chatflow.json post /chat-messages openapi: 3.0.1 info: title: Chatflow App API description: >- Chatflow applications support session persistence, allowing previous chat history to be used as context for responses. Chatflow apps use the `advanced-chat` mode, providing workflow-level streaming events for detailed execution tracking including node starts, finishes, iterations, and workflow lifecycle. version: 1.0.0 servers: - url: https://{api_base_url} description: >- Base URL of the Chatflow App API. For self-hosted deployments, replace it with your own API base URL. variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - name: Chatflows description: >- Operations for Chatflow apps, including chat messaging, workflow run details, and event streaming. - 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: TTS 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. paths: /chat-messages: post: tags: - Chatflows summary: Send Chat Message description: Send a request to the chat application. operationId: sendAdvancedChatMessage requestBody: description: Request body to send a chat message. required: true content: application/json: schema: $ref: '#/components/schemas/ChatRequest' 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: >- Successful response. 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: $ref: '#/components/schemas/ChatCompletionResponse' examples: blockingResponse: summary: Response Example - Blocking mode 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: >- A stream of Server-Sent Events (SSE). **Parsing**: Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\n\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which arrive as `event: ping` lines (no `data:` payload) every 10 seconds to keep the connection alive. **Stream lifecycle**: Workflow progress streams as `workflow_started`, node events (`node_started` and `node_finished`, plus iteration and loop variants), and the reply as `message` events (an LLM node with `reasoning_format: separated` also emits `reasoning_chunk` events alongside, carrying the model's chain-of-thought). The closing sequence depends on the outcome: - **Success**: `message_end`, then `workflow_finished` - **Failure**: `workflow_finished` with status `failed`, then `error`; no `message_end` - **Pause**: `human_input_required`, then `workflow_paused` (the stream ends here; the run resumes separately) When text-to-speech auto-play is enabled, `tts_message_end` trails the closing event. **Events**: Apart from `ping`, every event includes `conversation_id`, `message_id`, and `created_at` (Unix epoch seconds); all but `error` also include `task_id`. Workflow, node, and human-input events also nest their payload under `data` and, except for `agent_log`, carry a top-level `workflow_run_id`. **Reply events** | Event | Fires on | Key fields | |:---|:---|:---| | `message` | each answer chunk (concatenate in order) | `answer` | | `message_replace` | output moderation replaces the answer so far | `answer`, `reason` | | `reasoning_chunk` | each chain-of-thought delta, when an LLM node uses `reasoning_format: separated` (concatenate in order; a final `is_final: true` event marks thinking finished and may carry an empty `reasoning`) | `data.message_id`, `data.reasoning`, `data.node_id`, `data.is_final` | | `message_end` | the answer is complete | `metadata` (`usage`, `retriever_resources`) | | `tts_message`, `tts_message_end` | audio chunk / end, when TTS auto-play is on | `audio` | **Workflow and node events** Each event nests its payload under a `data` object. | Event | Fires on | Key `data` fields | |:---|:---|:---| | `workflow_started` | the run begins | `inputs` | | `node_started` | a node begins | `node_id`, `node_type`, `title` | | `node_finished` | a node ends | `status`, `outputs`, `execution_metadata` | | `node_retry` | a node retries after a failure | `retry_index` | | `iteration_started`, `iteration_next`, `iteration_completed` | Iteration node progress (informational) | `data` | | `loop_started`, `loop_next`, `loop_completed` | Loop node progress (informational) | `data` | | `agent_log` | an Agent node step log (informational; no `workflow_run_id`) | `data` | | `workflow_finished` | the run ends | `status` (`succeeded`, `failed`, `partial-succeeded`, `stopped`), `outputs`, `total_tokens` | | `workflow_paused` | the run pauses | `paused_nodes`, `reasons` | | `human_input_required` | the run reaches a Human Input node | `form_token`, `form_content`, `expiration_time` | After a pause this stream ends at `workflow_paused`. Submit the form via [Submit Human Input Form](/api-reference/human-input/submit-human-input-form) or let it time out; the resumed run, including `human_input_form_filled`/`human_input_form_timeout` through `workflow_finished`, streams from [Stream Workflow Events](/api-reference/chatflows/stream-workflow-events). **Transport events** | Event | Fires on | Key fields | |:---|:---|:---| | `error` | a failure ends the stream; HTTP stays `200` | `status` (e.g. `400`), `code` (e.g. `invalid_param`), `message` | | `ping` | keep-alive every 10 seconds | none | 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 (Workflow) 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: Response Example - Human Input pause 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` : App unavailable or misconfigured. - `not_chat_app` : App mode does not match the API route. - `conversation_completed` : The conversation has ended. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Text generation failed. - `bad_request` : Cannot use draft workflow 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` : Workflow 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` : Too many concurrent requests for this app. - `rate_limit_error` : The upstream model provider rate limit was exceeded. 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` : 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: User input/question content. inputs: type: object description: >- Allows the entry of various variable values defined by the App. Contains key/value pairs. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app. additionalProperties: true response_mode: type: string enum: - streaming - blocking description: >- Mode of response return. `streaming` (recommended) uses SSE. `blocking` returns after completion (may be interrupted for long processes). Cloudflare timeout is `100 s`. When omitted, defaults to blocking behavior. user: type: string description: >- User identifier, unique within the application. This identifier scopes data access — conversations, messages, and files are only visible when queried with the same `user` value. conversation_id: type: string description: >- Conversation ID to continue a conversation. Pass the previous message's `conversation_id`. To start a new conversation, omit this field or pass an empty string. The response will return a `conversation_id` — pass it in subsequent messages to continue that conversation. files: type: array description: >- File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`. items: type: object required: - type - transfer_method properties: type: type: string enum: - image - document - audio - video - custom description: File type. transfer_method: type: string enum: - remote_url - local_file description: >- Transfer method: `remote_url` for file URL, `local_file` for uploaded file. url: type: string format: url description: File URL (required when `transfer_method` is `remote_url`). upload_file_id: type: string description: >- Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`). auto_generate_name: type: boolean description: >- Auto-generate conversation title. If `false`, use the [Rename Conversation](/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation. default: true workflow_id: type: string description: >- Specify a published workflow version ID to execute. If not provided, the latest published version is used. ChatCompletionResponse: type: object properties: event: type: string description: Event type, fixed as `message`. task_id: type: string format: uuid description: Task ID for request tracking and stop response API. id: type: string format: uuid description: Unique ID of this response event. message_id: type: string format: uuid description: >- Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints. conversation_id: type: string format: uuid description: Conversation ID. mode: type: string description: App mode, fixed as `advanced-chat`. answer: type: string description: Complete response content. metadata: type: object description: Metadata including usage and retriever resources. properties: usage: $ref: '#/components/schemas/Usage' retriever_resources: type: array description: List of retriever resources used. items: $ref: '#/components/schemas/RetrieverResource' created_at: type: integer format: int64 description: Message creation timestamp (Unix epoch seconds). Usage: type: object description: Model usage information. properties: prompt_tokens: type: integer description: Number of tokens in the prompt. prompt_unit_price: type: string format: decimal description: Unit price per prompt token. prompt_price_unit: type: string format: decimal description: Price unit for prompt tokens. prompt_price: type: string format: decimal description: Total price for prompt tokens. completion_tokens: type: integer description: Number of tokens in the completion. completion_unit_price: type: string format: decimal description: Unit price per completion token. completion_price_unit: type: string format: decimal description: Price unit for completion tokens. completion_price: type: string format: decimal description: Total price for completion tokens. total_tokens: type: integer description: Total number of tokens used. total_price: type: string format: decimal description: Total price for all tokens. currency: type: string description: Currency for pricing. latency: type: number format: double description: Latency in seconds. RetrieverResource: type: object description: Citation and attribution information for a retriever resource. properties: id: type: string format: uuid description: Unique ID of the retriever resource. message_id: type: string format: uuid description: ID of the message this resource belongs to. position: type: integer description: Position of the resource in the list. dataset_id: type: string format: uuid description: ID of the knowledge base. dataset_name: type: string description: Name of the knowledge base. document_id: type: string format: uuid description: ID of the document. document_name: type: string description: Name of the document. data_source_type: type: string description: Type of the data source. segment_id: type: string format: uuid description: ID of the specific chunk within the document. score: type: number format: float description: Similarity score of the resource. hit_count: type: integer description: Number of times this chunk was hit. word_count: type: integer description: Word count of the chunk. segment_position: type: integer description: Position of the chunk within the document. index_node_hash: type: string description: Hash of the index node. content: type: string description: Content snippet from the resource. summary: type: string nullable: true description: Summary of the chunk content. created_at: type: integer format: int64 description: Creation timestamp (Unix epoch seconds). securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.** ````