Chat Messages

Send Chat Message

Changed on

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.

post/chat-messages

Request

  • Base URL
    https://api.dify.ai/v1
  • URL
    https://api.dify.ai/v1/chat-messages
  • Auth
    HTTP bearer

Request body

auto_generate_nameboolean

Auto-generate conversation title. If false, use the Rename Conversation API with auto_generate: true for async title generation.

conversation_idstring

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.

inputsobject 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.

querystring required

The user's message.

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.
  • Legacy Agent and Agent apps support streaming only; a blocking request fails with 400.
userstring 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.

workflow_idstring

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

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.
answerstring

Complete response content.

conversation_idstring uuid

Conversation ID.

created_atinteger

Message creation timestamp (Unix epoch seconds).

eventstring

Event type, fixed as message.

idstring uuid

Unique ID of this response event.

message_idstring uuid

Unique message ID. Use this as the message_id parameter when calling feedback or suggested questions endpoints.

modestring

App mode. chat for Chatbot apps, agent-chat for Legacy Agent apps, advanced-chat for Chatflow apps.

task_idstring uuid

Task ID for request tracking and stop response API.

Changes

  • 9b8ecd70c860Revision changes
    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

  • 3ff4555d5ddaRevision changes
    • info

      added the non-success response with the status