Dify Octri Demo
POST/chat-messages

Send Chat Message

Available for: Chatflow, Agent, Chatbot, Legacy 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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

8 body fields

Request body to send a chat message.

auto_generate_namebooleanoptional
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.
Default:true
conversation_idstringoptional
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).
filesarray<object>optional
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`. Agent apps accept file references but do not process their contents.
inputsobjectrequired
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).
querystringrequired
The user's message.
response_modestringoptional
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. - Legacy Agent and Agent apps support `streaming` only; a `blocking` request fails with 400.
Allowed:streamingblocking
userstringrequired
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).
workflow_idstringoptional
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.

6 status codes
200Successful 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.
answerstringoptional
Complete response content.
conversation_idstringoptional
Conversation ID.
created_atintegeroptional
Message creation timestamp (Unix epoch seconds).
eventstringoptional
Event type, fixed as `message`.
idstringoptional
Unique ID of this response event.
message_idstringoptional
Unique message ID. Use this as the `message_id` parameter when calling feedback or suggested questions endpoints.
metadataobjectoptional
Metadata including usage and retriever resources.
modestringoptional
App mode. `chat` for Chatbot apps, `agent-chat` for Legacy Agent apps, `advanced-chat` for Chatflow apps.
task_idstringoptional
Task ID for request tracking and stop response API.
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 an Agent app. - `invalid_param` : The Agent app has no bound Agent. - `agent_not_published` : The bound Agent has no published version. (Agent apps) - `conversation_completed` : The conversation has ended; start a new one by omitting `conversation_id`.

10 documented failures

  • app_unavailable

    App unavailable, please check your app configurations.

    app_unavailable

  • completion_request_error

    Completion request failed.

    completion_request_error

  • conversation_completed

    The conversation has ended. Please start a new conversation.

    conversation_completed

  • bad_request

    Cannot use draft workflow version. Workflow ID: a1b2c3d4-5678-90ab-cdef-1234567890ab.

    bad_request

  • model_currently_not_support

    Dify Hosted OpenAI trial currently not support the GPT-4 model.

    model_currently_not_support

  • invalid_param

    Agent App has no bound Agent

    invalid_param

  • agent_not_published

    Agent has not been published. Please publish the Agent before using the API.

    agent_not_published

  • not_chat_app

    Please check if your app mode matches the right API route.

    not_chat_app

  • provider_not_initialize

    No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

    provider_not_initialize

  • provider_quota_exceeded

    Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.

    provider_quota_exceeded

403`workflow_version_execution_not_allowed` : A Chatflow request pinned a workflow version via `workflow_id` on the Dify Cloud Sandbox plan.

One documented failure

  • workflow_version_execution_not_allowed

    Workflow version execution is not available on your current plan. Please upgrade to a paid plan.

    workflow_version_execution_not_allowed

404- `not_found` : Conversation does not exist. - `not_found` : Workflow not found with the specified `workflow_id`.

One documented failure

  • not_found

    Conversation Not Exists.

    not_found

429- `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached.

2 documented failures

  • rate_limit_error

    Workflow execution quota limit reached for tenant 8f1e2a90-3b7c-4d55-9a01-6c2f4e8b1d33

    rate_limit_error

  • too_many_requests

    Too many requests. Please try again later.

    too_many_requests

500`internal_server_error` : Internal server error.

One documented failure

  • internal_server_error

    The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application.

    internal_server_error

Error handling

A 400 is returned: - 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 an Agent app.
  • invalid_param : The Agent app has no bound Agent.
  • agent_not_published : The bound Agent has no published version. (Agent apps)
  • conversation_completed : The conversation has ended; start a new one by omitting conversation_id. A 403 is returned: workflow_version_execution_not_allowed : A Chatflow request pinned a workflow version via workflow_id on the Dify Cloud Sandbox plan. A 404 is returned: - not_found : Conversation does not exist.
  • not_found : Workflow not found with the specified workflow_id. A 429 is returned: - too_many_requests : Too many concurrent requests for this app.
  • rate_limit_error : The Dify Cloud workflow execution quota for this workspace has been reached. A 500 is returned: internal_server_error : Internal server error.