Skip to main content
POST
/
chat-messages
curl --request POST \
  --url https://{api_base_url}/chat-messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
    }
  ]
}
'
{
  "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": "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
}

Authorizations

​
Authorization
string
header
required

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. Requests with a missing or invalid API key fail with HTTP 401 and error code unauthorized.

Body

application/json

Request body to send a chat message.

​
query
string
required

User input/question content.

​
inputs
object
required

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 response to discover the variable names and types expected by your app.

​
user
string
required

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.

​
response_mode
enum<string>

Mode of response return. streaming (recommended) uses SSE. blocking returns after completion (may be interrupted for long processes; not supported in Agent Assistant mode). Cloudflare timeout is 100 s. When omitted, defaults to blocking behavior. New Agent apps support streaming only; blocking returns 400 bad_request.

Available options:
streaming,
blocking
​
conversation_id
string

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
object[]

File list for multimodal understanding, including images, documents, audio, and video. To attach a local file, first upload it via Upload File and use the returned id as upload_file_id with transfer_method: local_file. Not supported for New Agent apps: file references are accepted but their contents are not processed.

​
auto_generate_name
boolean
default:true

Auto-generate conversation title. If false, use the 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.

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

​
created_at
integer<int64>

Message creation timestamp (Unix epoch seconds).

Last modified on July 9, 2026