Send Chat Message
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.
curl --request POST \
--url 'https://{api_base_url}/chat-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--no-buffer \
--data '{"query": "What are the specs of the iPhone 13 Pro Max?", "inputs": {}, "response_mode": "streaming", "user": "{user}"}'import requests
url = "https://{api_base_url}/chat-messages"
payload = {
"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"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
}
]
})
};
fetch('https://{api_base_url}/chat-messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/chat-messages",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/chat-messages"
payload := strings.NewReader("{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"What are the specs of the iPhone 13 Pro Max?\",\n \"response_mode\": \"streaming\",\n \"conversation_id\": \"\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://cloud.dify.ai/logo/logo-site.png\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{api_base_url}/chat-messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"What are the specs of the iPhone 13 Pro Max?\",\n \"response_mode\": \"streaming\",\n \"conversation_id\": \"\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://cloud.dify.ai/logo/logo-site.png\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/chat-messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"What are the specs of the iPhone 13 Pro Max?\",\n \"response_mode\": \"streaming\",\n \"conversation_id\": \"\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://cloud.dify.ai/logo/logo-site.png\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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
Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Body
Request body to send a chat message.
The user's message.
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.
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.
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
streamingonly; ablockingrequest fails with 400.
streaming, blocking 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.
Files to attach to the message. For a local file, first upload it via 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.
Show child attributes
Show child attributes
Auto-generate conversation title. If false, use the Rename Conversation API with auto_generate: true for async title generation.
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_modeisblocking, returnsapplication/jsonwith aChatCompletionResponseobject. - If
response_modeisstreaming, returnstext/event-streamwith a stream of Server-Sent Events.
Event type, fixed as message.
Task ID for request tracking and stop response API.
Unique ID of this response event.
Unique message ID. Use this as the message_id parameter when calling feedback or suggested questions endpoints.
Conversation ID.
App mode. chat for Chatbot apps, agent-chat for Agent apps, advanced-chat for Chatflow apps.
Complete response content.
Metadata including usage and retriever resources.
Show child attributes
Show child attributes
Message creation timestamp (Unix epoch seconds).
Was this page helpful?
curl --request POST \
--url 'https://{api_base_url}/chat-messages' \
--header 'Authorization: Bearer {api_key}' \
--header 'Content-Type: application/json' \
--no-buffer \
--data '{"query": "What are the specs of the iPhone 13 Pro Max?", "inputs": {}, "response_mode": "streaming", "user": "{user}"}'import requests
url = "https://{api_base_url}/chat-messages"
payload = {
"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"
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'
}
]
})
};
fetch('https://{api_base_url}/chat-messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{api_base_url}/chat-messages",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{api_base_url}/chat-messages"
payload := strings.NewReader("{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"What are the specs of the iPhone 13 Pro Max?\",\n \"response_mode\": \"streaming\",\n \"conversation_id\": \"\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://cloud.dify.ai/logo/logo-site.png\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{api_base_url}/chat-messages")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"What are the specs of the iPhone 13 Pro Max?\",\n \"response_mode\": \"streaming\",\n \"conversation_id\": \"\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://cloud.dify.ai/logo/logo-site.png\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{api_base_url}/chat-messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inputs\": {\n \"city\": \"San Francisco\"\n },\n \"query\": \"What are the specs of the iPhone 13 Pro Max?\",\n \"response_mode\": \"streaming\",\n \"conversation_id\": \"\",\n \"user\": \"abc-123\",\n \"files\": [\n {\n \"type\": \"image\",\n \"transfer_method\": \"remote_url\",\n \"url\": \"https://cloud.dify.ai/logo/logo-site.png\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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
}