---
title: "Send Chat Message"
method: POST
path: "/chat-messages"
tags: ["Chat Messages"]
---

# Send Chat Message

`POST /chat-messages`

**Available for**: Chatflow, New Agent, Chatbot, Agent apps.

Sends a message to a chat app and returns the assistant's reply. The events in the streaming response vary by app type.

## Request body

- ChatRequest
  - `query` string, required — The user's message.
  - `inputs` object, required — Values for the app's input variables, keyed by variable name. The expected names and types come from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters).
  - `response_mode` 'streaming' | 'blocking' — Mode of response return. Defaults to blocking when omitted. - `streaming` (recommended): the reply arrives as Server-Sent Events. - `blocking`: returns once generation completes. Long generations risk interruption: on Dify Cloud, the edge proxy may end the connection if the response doesn't arrive within its timeout. - Agent and New Agent apps support `streaming` only; a `blocking` request fails with 400.
  - `user` string, required — 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/api-reference/guides/end-user-identity).
  - `conversation_id` string — 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/api-reference/conversations/list-conversations).
  - `files` object[] — Files to attach to the message. For a local file, first upload it via [Upload File](/en/api-reference/files/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`. New Agent apps accept file references but do not process their contents.
    - `type` 'image' | 'document' | 'audio' | 'video' | 'custom', required — File type.
    - `transfer_method` 'remote_url' | 'local_file', required — Transfer method: `remote_url` for file URL, `local_file` for uploaded file.
    - `url` string, url — File URL (required when `transfer_method` is `remote_url`).
    - `upload_file_id` string — Uploaded file ID obtained from the [Upload File](/en/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`).
  - `auto_generate_name` boolean — Auto-generate conversation title. If `false`, use the [Rename Conversation](/en/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation.
  - `workflow_id` string — Chatflow apps only. Specify a published workflow version ID to execute. If not provided, the latest published version is used. On Dify Cloud, pinning a version requires a paid plan.

## Response `200`

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.

- ChatCompletionResponse
  - `event` string — Event type, fixed as `message`.
  - `task_id` string, uuid — Task ID for request tracking and stop response API.
  - `id` string, uuid — Unique ID of this response event.
  - `message_id` string, uuid — Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints.
  - `conversation_id` string, uuid — Conversation ID.
  - `mode` string — App mode. `chat` for Chatbot apps, `agent-chat` for Agent apps, `advanced-chat` for Chatflow apps.
  - `answer` string — Complete response content.
  - `metadata` object — Metadata including usage and retriever resources.
    - `usage` Usage — Model usage information.
      - `prompt_tokens` integer — Number of tokens in the prompt.
      - `prompt_unit_price` string, decimal — Unit price per prompt token.
      - `prompt_price_unit` string, decimal — Price unit for prompt tokens.
      - `prompt_price` string, decimal — Total price for prompt tokens.
      - `completion_tokens` integer — Number of tokens in the completion.
      - `completion_unit_price` string, decimal — Unit price per completion token.
      - `completion_price_unit` string, decimal — Price unit for completion tokens.
      - `completion_price` string, decimal — Total price for completion tokens.
      - `total_tokens` integer — Total number of tokens used.
      - `total_price` string, decimal — Total price for all tokens.
      - `currency` string — Currency for pricing.
      - `latency` number, double — Latency in seconds.
    - `retriever_resources` RetrieverResource[] — List of retriever resources used.
      - `id` string, uuid — Unique ID of the retriever resource.
      - `message_id` string, uuid — ID of the message this resource belongs to.
      - `position` integer — Position of the resource in the list.
      - `dataset_id` string, uuid — ID of the knowledge base.
      - `dataset_name` string — Name of the knowledge base.
      - `document_id` string, uuid — ID of the document.
      - `document_name` string — Name of the document.
      - `data_source_type` string — Type of the data source.
      - `segment_id` string, uuid — ID of the specific chunk within the document.
      - `score` number, float — Similarity score of the resource.
      - `hit_count` integer — Number of times this chunk was hit.
      - `word_count` integer — Word count of the chunk.
      - `segment_position` integer — Position of the chunk within the document.
      - `index_node_hash` string — Hash of the index node.
      - `content` string — Content snippet from the resource.
      - `summary` string, nullable — Summary of the chunk content.
      - `created_at` integer — Creation timestamp (Unix epoch seconds).
  - `created_at` integer — Message creation timestamp (Unix epoch seconds).

## Other responses

- `400` — - `app_unavailable` : App unavailable or misconfigured. - `not_chat_app` : App mode does not match the API route. - `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. - `bad_request` : `blocking` response mode with a New Agent app. - `invalid_param` : The New Agent app has no bound Agent. - `agent_not_published` : The bound Agent has no published version. (New Agent apps) - `conversation_completed` : The conversation has ended; start a new one by omitting `conversation_id`.
- `403` — `workflow_version_execution_not_allowed` : A Chatflow request pinned a workflow version via `workflow_id` on the Dify Cloud Sandbox plan.
- `404` — - `not_found` : Conversation does not exist. - `not_found` : Workflow not found with the specified `workflow_id`.
- `429` — - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The workspace's Dify Cloud quota for workflow executions has been exhausted.
- `500` — `internal_server_error` : Internal server error.

---

[API](https://skmtc.net/langgenius/apis/dify-service-api.md) · [All operations](https://skmtc.net/langgenius/apis/dify-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/langgenius/dify-service-api/revisions/e49b3db72bad/schema)