centersl/dify-docs
1
0
Fork 0
mirror of https://github.com/langgenius/dify-docs.git synced 2026-04-12 06:07:37 +07:00
Code Issues Packages Projects Releases Wiki Activity
Files
5cebbd9fc3269b8c19bb25e69027983fb4479e63
dify-docs/api_access/chat.en.mdx
Alter-xyz 34c89359db chore: contributing in page
2025-05-12 02:41:59 +08:00

1216 lines
44 KiB
Plaintext
Raw Blame History

---
title: Chatbot
---
Chat applications support session persistence, allowing previous chat history to be used as context for responses. This can be applicable for chatbot, customer service AI, etc.
### Base URL
```text
https://api.dify.ai/v1
```
### Authentication
The Service API uses `API-Key` authentication.
<i>
**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.**
</i>
For all API requests, include your API Key in the `Authorization` HTTP Header, as shown below:
```text
Authorization: Bearer {YOUR_API_KEY}
```
---
## POST /chat-messages Send Chat Message
Send a request to the chat application.
### Request Body
- `query` (string): User Input/Question content.
- `inputs` (object, optional, default `{}`): Allows the entry of various variable values defined by the App. The `inputs` parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable.
- `response_mode` (string): The mode of response return, supporting:
- `streaming`: Streaming mode (recommended), implements a typewriter-like output through SSE ([Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)).
- `blocking`: Blocking mode, returns result after execution is complete. (Requests may be interrupted if the process is long). Due to Cloudflare restrictions, the request will be interrupted without a return after 100 seconds.
<i>Note: blocking mode is not supported in Agent Assistant mode.</i>
- `user` (string): User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.
- `conversation_id` (string, optional): Conversation ID. To continue the conversation based on previous chat records, it is necessary to pass the previous message's `conversation_id`.
- `files` (array[object], optional): File list, suitable for inputting files (images) combined with text understanding and answering questions, available only when the model supports Vision capability.
- `type` (string): Supported type: `image` (currently only supports image type).
- `transfer_method` (string): Transfer method, `remote_url` for image URL / `local_file` for file upload.
- `url` (string, conditional): Image URL (when the transfer method is `remote_url`).
- `upload_file_id` (string, conditional): Uploaded file ID, which must be obtained by uploading through the File Upload API in advance (when the transfer method is `local_file`).
- `auto_generate_name` (bool, optional, default `true`): Auto-generate title. If set to `false`, can achieve async title generation by calling the conversation rename API and setting `auto_generate` to `true`.
### Response
When `response_mode` is `blocking`, returns a `ChatCompletionResponse` object.
When `response_mode` is `streaming`, returns a `ChunkChatCompletionResponse` stream.
#### ChatCompletionResponse
Returns the complete App result, `Content-Type` is `application/json`.
- `event` (string): Event type, fixed as `message`.
- `task_id` (string): Task ID, used for request tracking and the Stop Generate API.
- `id` (string): Unique ID.
- `message_id` (string): Unique message ID.
- `conversation_id` (string): Conversation ID.
- `mode` (string): App mode, fixed as `chat`.
- `answer` (string): Complete response content.
- `metadata` (object): Metadata.
- `usage` (Usage): Model usage information.
- `retriever_resources` (array[RetrieverResource]): Citation and Attribution List.
- `created_at` (int): Message creation timestamp, e.g., `1705395332`.
#### ChunkChatCompletionResponse
Returns the stream chunks outputted by the App, `Content-Type` is `text/event-stream`.
Each streaming chunk starts with `data:`, separated by two newline characters `\n\n`, as shown below:
```streaming
data: {"event": "message", "task_id": "900bbd43-dc0b-4383-a372-aa6e6c414227", "id": "663c5084-a254-4040-8ad3-51f2a3c1a77c", "answer": "Hi", "created_at": 1705398420}\n\n
```
The structure of the streaming chunks varies depending on the `event`:
- `event: message`: LLM returns text chunk event, i.e., the complete text is output in a chunked fashion.
- `task_id` (string): Task ID, used for request tracking and the below Stop Generate API.
- `message_id` (string): Unique message ID.
- `conversation_id` (string): Conversation ID.
- `answer` (string): LLM returned text chunk content.
- `created_at` (int): Creation timestamp, e.g., `1705395332`.
- `event: agent_message`: LLM returns text chunk event, i.e., with Agent Assistant enabled, the complete text is output in a chunked fashion (Only supported in Agent mode).
- `task_id` (string): Task ID.
- `message_id` (string): Unique message ID.
- `conversation_id` (string): Conversation ID.
- `answer` (string): LLM returned text chunk content.
- `created_at` (int): Creation timestamp.
- `event: tts_message`: TTS audio stream event. Speech synthesis output. Content is an audio block in Mp3 format, base64 encoded. Decode base64 and feed to player. (Available only when auto-play is enabled).
- `task_id` (string): Task ID.
- `message_id` (string): Unique message ID.
- `audio` (string): Base64 encoded audio content.
- `created_at` (int): Creation timestamp.
- `event: tts_message_end`: TTS audio stream end event.
- `task_id` (string): Task ID.
- `message_id` (string): Unique message ID.
- `audio` (string): Empty string for this event.
- `created_at` (int): Creation timestamp.
- `event: agent_thought`: Thought of Agent, contains LLM thought, tool call input/output (Only supported in Agent mode).
- `id` (string): Agent thought ID.
- `task_id` (string): Task ID.
- `message_id` (string): Unique message ID.
- `position` (int): Position of current agent thought.
- `thought` (string): What LLM is thinking.
- `observation` (string): Response from tool calls.
- `tool` (string): List of tools called, separated by `;`.
- `tool_input` (string): JSON formatted tool input. E.g., `{"dalle3": {"prompt": "a cute cat"}}`.
- `created_at` (int): Creation timestamp.
- `message_files` (array[string]): File IDs.
- `file_id` (string): File ID.
- `conversation_id` (string): Conversation ID.
- `event: message_file`: Message file event, a new file created by a tool.
- `id` (string): File unique ID.
- `type` (string): File type, currently only "image".
- `belongs_to` (string): Belongs to, will only be 'assistant' here.
- `url` (string): Remote URL of the file.
- `conversation_id` (string): Conversation ID.
- `event: message_end`: Message end event, streaming has ended.
- `task_id` (string): Task ID.
- `message_id` (string): Unique message ID.
- `conversation_id` (string): Conversation ID.
- `metadata` (object): Metadata.
- `usage` (Usage): Model usage information.
- `retriever_resources` (array[RetrieverResource]): Citation and Attribution List.
- `event: message_replace`: Message content replacement event. If content moderation flags content, it's replaced via this event.
- `task_id` (string): Task ID.
- `message_id` (string): Unique message ID.
- `conversation_id` (string): Conversation ID.
- `answer` (string): Replacement content.
- `created_at` (int): Creation timestamp.
- `event: error`: Exceptions during streaming. Reception ends the stream.
- `task_id` (string): Task ID.
- `message_id` (string): Unique message ID.
- `status` (int): HTTP status code.
- `code` (string): Error code.
- `message` (string): Error message.
- `event: ping`: Ping event every 10 seconds to keep the connection alive.
### Errors
- 404, Conversation does not exist.
- 400, `invalid_param`, abnormal parameter input.
- 400, `app_unavailable`, App configuration unavailable.
- 400, `provider_not_initialize`, no available model credential configuration.
- 400, `provider_quota_exceeded`, model invocation quota insufficient.
- 400, `model_currently_not_support`, current model unavailable.
- 400, `completion_request_error`, text generation failed.
- 500, internal server error.
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/chat-messages' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {},
"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"
}
]
}'
```
</CodeGroup>
<CodeGroup>
```json "Blocking Mode Response"
{
"event": "message",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
"id": "9da23599-e713-473b-982c-4328d4f5c78a",
"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\"\n\"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
}
```
```streaming "Streaming (Basic Assistant)"
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595}
data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}, "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\"\n\"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\""}]}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
```streaming "Streaming (Agent Assistant)"
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " I", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": "'m", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " glad", "created_at": 1679586595}
data: {"event": "message", "message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " to", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " meet", "created_at": 1679586595}
data: {"event": "message", "message_id" : "5ad4cb98-f0c7-4085-b384-88c403be6290", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "answer": " you", "created_at": 1679586595}
data: {"event": "message_end", "id": "5e52ce04-874b-4d27-9045-b3bc80def685", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "metadata": {"usage": {"prompt_tokens": 1033, "prompt_unit_price": "0.001", "prompt_price_unit": "0.001", "prompt_price": "0.0010330", "completion_tokens": 135, "completion_unit_price": "0.002", "completion_price_unit": "0.001", "completion_price": "0.0002700", "total_tokens": 1168, "total_price": "0.0013030", "currency": "USD", "latency": 1.381760165997548}, "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\"\n\"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\""}]}}
data: {"event": "tts_message", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": "qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq"}
data: {"event": "tts_message_end", "conversation_id": "23dd85f3-1a41-4ea0-b7a9-062734ccfaf9", "message_id": "a8bdc41c-13b2-4c18-bfd9-054b9803038c", "created_at": 1721205487, "task_id": "3bf8a0bb-e73b-4690-9e66-4e429bad8ee7", "audio": ""}
```
</CodeGroup>
---
## POST /files/upload File Upload
Upload a file (currently only images are supported) for use when sending messages, enabling multimodal understanding of images and text.
Supports png, jpg, jpeg, webp, gif formats.
Uploaded files are for use by the current end-user only.
### Request Body
This interface requires a `multipart/form-data` request.
- `file` (File, Required): The file to be uploaded.
- `user` (string, Required): User identifier, defined by the developer's rules, must be unique within the application.
### Response
After a successful upload, the server will return the file's ID and related information.
- `id` (uuid): ID.
- `name` (string): File name.
- `size` (int): File size (bytes).
- `extension` (string): File extension.
- `mime_type` (string): File mime-type.
- `created_by` (uuid): End-user ID.
- `created_at` (timestamp): Creation timestamp, e.g., `1705395332`.
### Errors
- 400, `no_file_uploaded`, a file must be provided.
- 400, `too_many_files`, currently only one file is accepted.
- 400, `unsupported_preview`, the file does not support preview.
- 400, `unsupported_estimate`, the file does not support estimation.
- 413, `file_too_large`, the file is too large.
- 415, `unsupported_file_type`, unsupported extension.
- 503, `s3_connection_failed`, unable to connect to S3 service.
- 503, `s3_permission_denied`, no permission to upload files to S3.
- 503, `s3_file_too_large`, file exceeds S3 size limit.
- 500, internal server error.
<CodeGroup>
```bash cURL curl -X POST 'https://api.dify.ai/v1/files/upload' \ --header
'Authorization: Bearer {YOUR_API_KEY}' \ --form
'file=@"/path/to/your/localfile.png";type=image/png' \ --form
'user="abc-123"' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "72fa9618-8f89-4a37-9b33-7e1178a24a67",
"name": "example.png",
"size": 1024,
"extension": "png",
"mime_type": "image/png",
"created_by": "6ad1ab0a-73ff-4ac1-b9e4-cdb312f71f13",
"created_at": 1577836800
}
```
</CodeGroup>
---
## POST /chat-messages/:task_id/stop Stop Generate
Only supported in streaming mode.
### Path Parameters
- `task_id` (string): Task ID, can be obtained from the streaming chunk return.
### Request Body
- `user` (string, Required): User identifier, used to define the identity of the end-user, must be consistent with the user passed in the send message interface.
### Response
- `result` (string): Always returns "success".
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/chat-messages/:task_id/stop' \
-H 'Authorization: Bearer {YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## POST /messages/:message_id/feedbacks Message Feedback
End-users can provide feedback messages, facilitating application developers to optimize expected outputs.
### Path Parameters
- `message_id` (string): Message ID.
### Request Body
- `rating` (string): Upvote as `like`, downvote as `dislike`, revoke upvote/downvote as `null`.
- `user` (string): User identifier, defined by the developer's rules, must be unique within the application.
- `content` (string, optional): The specific content of message feedback.
### Response
- `result` (string): Always returns "success".
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/messages/:message_id/feedbacks' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"rating": "like",
"user": "abc-123",
"content": "message feedback information"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success"
}
```
</CodeGroup>
---
## GET /messages/:message_id/suggested Next Suggested Questions
Get next questions suggestions for the current message.
### Path Parameters
- `message_id` (string): Message ID.
### Query Parameters
- `user` (string): User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.
<CodeGroup>
```bash cURL curl --location --request GET 'https://api.dify.ai/v1/messages/
{message_id}/suggested?user=abc-123' \ --header 'Authorization: Bearer {
YOUR_API_KEY
}' \ --header 'Content-Type: application/json' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"result": "success",
"data": [
"a",
"b",
"c"
]
}
```
</CodeGroup>
---
## GET /messages Get Conversation History Messages
Returns historical chat records in a scrolling load format, with the first page returning the latest `{limit}` messages, i.e., in reverse order.
### Query Parameters
- `conversation_id` (string): Conversation ID.
- `user` (string): User identifier.
- `first_id` (string, optional): The ID of the first chat record on the current page, default is null.
- `limit` (int, optional, default `20`): How many chat history messages to return in one request.
### Response
- `data` (array[object]): Message list.
- `id` (string): Message ID.
- `conversation_id` (string): Conversation ID.
- `inputs` (object): User input parameters.
- `query` (string): User input / question content.
- `message_files` (array[object]): Message files.
- `id` (string): ID.
- `type` (string): File type, `image` for images.
- `url` (string): Preview image URL.
- `belongs_to` (string): Belongs to, `user` or `assistant`.
- `agent_thoughts` (array[object]): Agent thought (Empty if it's a Basic Assistant).
- `id` (string): Agent thought ID.
- `message_id` (string): Unique message ID.
- `position` (int): Position of current agent thought.
- `thought` (string): What LLM is thinking.
- `observation` (string): Response from tool calls.
- `tool` (string): List of tools called, separated by `;`.
- `tool_input` (string): JSON formatted tool input.
- `created_at` (int): Creation timestamp.
- `message_files` (array[string]): File IDs.
- `file_id` (string): File ID.
- `answer` (string): Response message content.
- `created_at` (timestamp): Creation timestamp.
- `feedback` (object, optional): Feedback information.
- `rating` (string): `like` / `dislike`.
- `retriever_resources` (array[RetrieverResource]): Citation and Attribution List.
- `has_more` (bool): Whether there is a next page.
- `limit` (int): Number of returned items.
<CodeGroup>
```bash cURL curl -X GET
'https://api.dify.ai/v1/messages?user=abc-123&conversation_id=
{YOUR_CONVERSATION_ID}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json "Basic Assistant Response"
{
"limit": 20,
"has_more": false,
"data": [
{
"id": "a076a87f-31e5-48dc-b452-0061adbbc922",
"conversation_id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
"inputs": {
"name": "dify"
},
"query": "iphone 13 pro",
"answer": "The iPhone 13 Pro, released on September 24, 2021, features a 6.1-inch display...",
"message_files": [],
"feedback": null,
"retriever_resources": [
{
"position": 1,
"dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
// ... more retriever_resources fields
"content": "\"Model\",\"Release Date\",\"Display Size\"..."
}
],
"agent_thoughts": [],
"created_at": 1705569239
}
]
}
```
```json "Agent Assistant Response"
{
"limit": 20,
"has_more": false,
"data": [
{
"id": "d35e006c-7c4d-458f-9142-be4930abdf94",
"conversation_id": "957c068b-f258-4f89-ba10-6e8a0361c457",
"inputs": {},
"query": "draw a cat",
"answer": "I have generated an image of a cat for you...",
"message_files": [
{
"id": "976990d2-5294-47e6-8f14-7356ba9d2d76",
"type": "image",
"url": "http://127.0.0.1:5001/files/tools/...",
"belongs_to": "assistant"
}
],
"feedback": null,
"retriever_resources": [],
"created_at": 1705988187,
"agent_thoughts": [
{
"id": "592c84cf-07ee-441c-9dcc-ffc66c033469",
// ... more agent_thoughts fields
"files": [
"976990d2-5294-47e6-8f14-7356ba9d2d76"
]
},
{
"id": "73ead60d-2370-4780-b5ed-532d2762b0e5",
// ... more agent_thoughts fields
"files": []
}
]
}
]
}
```
</CodeGroup>
---
## GET /conversations Get Conversations
Retrieve the conversation list for the current user, defaulting to the most recent 20 entries.
### Query Parameters
- `user` (string): User identifier.
- `last_id` (string, optional): The ID of the last record on the current page, default is null.
- `limit` (int, optional, default `20`, max `100`, min `1`): How many records to return.
- `sort_by` (string, optional, default `-updated_at`): Sorting Field. Available: `created_at`, `-created_at`, `updated_at`, `-updated_at`. `-` denotes descending.
### Response
- `data` (array[object]): List of conversations.
- `id` (string): Conversation ID.
- `name` (string): Conversation name.
- `inputs` (object): User input parameters.
- `status` (string): Conversation status.
- `introduction` (string): Introduction.
- `created_at` (timestamp): Creation timestamp.
- `updated_at` (timestamp): Update timestamp.
- `has_more` (bool): Whether there is a next page.
- `limit` (int): Number of entries returned.
<CodeGroup>
```bash cURL curl -X GET
'https://api.dify.ai/v1/conversations?user=abc-123&last_id=&limit=20' \
--header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"limit": 20,
"has_more": false,
"data": [
{
"id": "10799fb8-64f7-4296-bbf7-b42bfbe0ae54",
"name": "New chat",
"inputs": {
"book": "book",
"myName": "Lucy"
},
"status": "normal",
"created_at": 1679667915,
"updated_at": 1679667915
},
{
"id": "hSIhXBhNe8X1d8Et"
// ...
}
]
}
```
</CodeGroup>
---
## DELETE /conversations/:conversation_id Delete Conversation
Delete a conversation.
### Path Parameters
- `conversation_id` (string): Conversation ID.
### Request Body
- `user` (string): The user identifier.
### Response
- `204 No Content`
<CodeGroup>
```bash cURL
curl -X DELETE 'https://api.dify.ai/v1/conversations/{conversation_id}' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>```text Response 204 No Content ```</CodeGroup>
---
## POST /conversations/:conversation_id/name Conversation Rename
Rename the session. The session name is used for display on clients that support multiple sessions.
### Path Parameters
- `conversation_id` (string): Conversation ID.
### Request Body
- `name` (string, optional): The name of the conversation. Can be omitted if `auto_generate` is `true`.
- `auto_generate` (bool, optional, default `false`): Automatically generate the title.
- `user` (string): The user identifier.
### Response
- `id` (string): Conversation ID.
- `name` (string): Conversation name.
- `inputs` (object): User input parameters.
- `status` (string): Conversation status.
- `introduction` (string): Introduction.
- `created_at` (timestamp): Creation timestamp.
- `updated_at` (timestamp): Update timestamp.
<CodeGroup>
```bash cURL
curl -X POST 'https://api.dify.ai/v1/conversations/{conversation_id}/name' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "",
"auto_generate": true,
"user": "abc-123"
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "cd78daf6-f9e4-4463-9ff2-54257230a0ce",
"name": "Chat vs AI",
"inputs": {},
"status": "normal",
"introduction": "",
"created_at": 1705569238,
"updated_at": 1705569238
}
```
</CodeGroup>
---
## GET /conversations/:conversation_id/variables Get Conversation Variables
Retrieve variables from a specific conversation. Useful for extracting structured data captured during the conversation.
### Path Parameters
- `conversation_id` (string): The ID of the conversation.
### Query Parameters
- `user` (string): The user identifier.
- `last_id` (string, optional): The ID of the last record on the current page, default is null.
- `limit` (int, optional, default `20`, max `100`, min `1`): Number of records to return.
- `variable_name` (string, optional): Filter by a specific variable name.
### Response
- `limit` (int): Number of items per page.
- `has_more` (bool): Whether there is a next page.
- `data` (array[object]): List of variables.
- `id` (string): Variable ID.
- `name` (string): Variable name.
- `value_type` (string): Variable type (e.g., string, number, object).
- `value` (string): Variable value.
- `description` (string): Variable description.
- `created_at` (int): Creation timestamp.
- `updated_at` (int): Last update timestamp.
### Errors
- 404, `conversation_not_exists`, Conversation not found.
<CodeGroup>
```bash "Get all variables" curl -X GET
'https://api.dify.ai/v1/conversations/{conversation_id}
/variables?user=abc-123' \ --header 'Authorization: Bearer {YOUR_API_KEY}' ```
```bash "Filter by variable name" curl -X GET 'https://api.dify.ai/v1/conversations/
{conversation_id}
/variables?user=abc-123&variable_name=customer_name' \ --header
'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"limit": 100,
"has_more": false,
"data": [
{
"id": "variable-uuid-1",
"name": "customer_name",
"value_type": "string",
"value": "John Doe",
"description": "Customer name extracted from the conversation",
"created_at": 1650000000000,
"updated_at": 1650000000000
},
{
"id": "variable-uuid-2",
"name": "order_details",
"value_type": "json",
"value": "{\"product\":\"Widget\",\"quantity\":5,\"price\":19.99}",
"description": "Order details from the customer",
"created_at": 1650000000000,
"updated_at": 1650000000000
}
]
}
```
</CodeGroup>
---
## POST /audio-to-text Speech to Text
This endpoint requires a `multipart/form-data` request.
### Request Body
- `file` (file): Audio file.
Supported formats: `mp3, mp4, mpeg, mpga, m4a, wav, webm`.
File size limit: 15MB.
- `user` (string): User identifier.
### Response
- `text` (string): Output text.
<CodeGroup>
```bash cURL curl -X POST 'https://api.dify.ai/v1/audio-to-text' \ --header
'Authorization: Bearer {YOUR_API_KEY}' \ --form
'file=@"/path/to/your/audiofile.mp3";type=audio/mp3' \ --form
'user="abc-123"' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"text": "Transcribed text from audio."
}
```
</CodeGroup>
---
## POST /text-to-audio Text to Audio
Text to speech.
### Request Body
- `message_id` (string, optional): For text messages generated by Dify, pass the `message_id`. Backend uses it to find content for synthesis. Priority over `text` if both provided.
- `text` (string, optional): Speech content to generate. Required if `message_id` is not provided.
- `user` (string): The user identifier.
### Response
The response is an audio file stream.
**Headers:**
- `Content-Type`: `audio/wav` (or other audio format depending on system configuration)
<CodeGroup>
```bash cURL
curl --location --request POST 'https://api.dify.ai/v1/text-to-audio' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"text": "Hello Dify",
"user": "abc-123"
}' \
--output 'output.wav'
```
To use `message_id`:
```bash cURL with message_id
curl --location --request POST 'https://api.dify.ai/v1/text-to-audio' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"message_id": "5ad4cb98-f0c7-4085-b384-88c403be6290",
"user": "abc-123"
}' \
--output 'output.wav'
```
</CodeGroup>
<CodeGroup>
```text "Response Headers" Content-Type: audio/wav // ... other headers ...
``` ```text "Response Body" (Binary audio data) ```
</CodeGroup>
---
## GET /info Get Application Basic Information
Used to get basic information about this application.
### Response
- `name` (string): Application name.
- `description` (string): Application description.
- `tags` (array[string]): Application tags.
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/info' \ -H 'Authorization:
Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"name": "My App",
"description": "This is my app.",
"tags": [
"tag1",
"tag2"
]
}
```
</CodeGroup>
---
## GET /parameters Get Application Parameters Information
Used at the start of entering the page to obtain information such as features, input parameter names, types, and default values.
### Query Parameters
- `user` (string): User identifier.
### Response
- `opening_statement` (string): Opening statement.
- `suggested_questions` (array[string]): List of suggested questions for the opening.
- `suggested_questions_after_answer` (object): Suggest questions after enabling the answer.
- `enabled` (bool): Whether it is enabled.
- `speech_to_text` (object): Speech to text.
- `enabled` (bool): Whether it is enabled.
- `retriever_resource` (object): Citation and Attribution.
- `enabled` (bool): Whether it is enabled.
- `annotation_reply` (object): Annotation reply.
- `enabled` (bool): Whether it is enabled.
- `user_input_form` (array[object]): User input form configuration.
- `text-input` (object): Text input control.
- `label` (string): Variable display label name.
- `variable` (string): Variable ID.
- `required` (bool): Whether it is required.
- `default` (string): Default value.
- `paragraph` (object): Paragraph text input control.
- `label` (string): Variable display label name.
- `variable` (string): Variable ID.
- `required` (bool): Whether it is required.
- `default` (string): Default value.
- `select` (object): Dropdown control.
- `label` (string): Variable display label name.
- `variable` (string): Variable ID.
- `required` (bool): Whether it is required.
- `default` (string): Default value.
- `options` (array[string]): Option values.
- `file_upload` (object): File upload configuration.
- `image` (object): Image settings. Currently supports `png, jpg, jpeg, webp, gif`.
- `enabled` (bool): Whether it is enabled.
- `number_limits` (int): Image number limit (default 3).
- `transfer_methods` (array[string]): List of transfer methods (`remote_url`, `local_file`).
- `system_parameters` (object): System parameters.
- `file_size_limit` (int): Document upload size limit (MB).
- `image_file_size_limit` (int): Image file upload size limit (MB).
- `audio_file_size_limit` (int): Audio file upload size limit (MB).
- `video_file_size_limit` (int): Video file upload size limit (MB).
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/parameters?user=abc-123' \
--header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"opening_statement": "Hello!",
"suggested_questions_after_answer": {
"enabled": true
},
"speech_to_text": {
"enabled": true
},
"retriever_resource": {
"enabled": true
},
"annotation_reply": {
"enabled": true
},
"user_input_form": [
{
"paragraph": {
"label": "Query",
"variable": "query",
"required": true,
"default": ""
}
}
],
"file_upload": {
"image": {
"enabled": false,
"number_limits": 3,
"detail": "high",
"transfer_methods": [
"remote_url",
"local_file"
]
}
},
"system_parameters": {
"file_size_limit": 15,
"image_file_size_limit": 10,
"audio_file_size_limit": 50,
"video_file_size_limit": 100
}
}
```
</CodeGroup>
---
## GET /meta Get Application Meta Information
Used to get icons of tools in this application.
### Response
- `tool_icons` (object): Tool icons.
- `tool_name` (string): Key is the tool name.
- `icon` (object|string): Icon can be an object or a URL string.
- (object) `background` (string): Background color in hex.
- (object) `content` (string): Emoji or icon character.
- (string) URL of the icon.
<CodeGroup>
```bash cURL curl -X GET 'https://api.dify.ai/v1/meta' \ -H 'Authorization:
Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"tool_icons": {
"dalle2": "https://cloud.dify.ai/console/api/workspaces/current/tool-provider/builtin/dalle/icon",
"api_tool": {
"background": "#252525",
"content": "\ud83d\ude01"
}
}
}
```
</CodeGroup>
---
## GET /apps/annotations Get Annotation List
### Query Parameters
- `page` (int, optional, default `1`): Page number.
- `limit` (int, optional, default `20`, range `1-100`): Number of items returned.
<CodeGroup>
```bash cURL curl --location --request GET
'https://api.dify.ai/v1/apps/annotations?page=1&limit=20' \ --header
'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"data": [
{
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
"question": "What is your name?",
"answer": "I am Dify.",
"hit_count": 0,
"created_at": 1735625869
}
],
"has_more": false,
"limit": 20,
"total": 1,
"page": 1
}
```
</CodeGroup>
---
## POST /apps/annotations Create Annotation
### Request Body
- `question` (string): Question.
- `answer` (string): Answer.
<CodeGroup>
```bash cURL
curl --location --request POST 'https://api.dify.ai/v1/apps/annotations' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"question": "What is your name?",
"answer": "I am Dify."
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "69d48372-ad81-4c75-9c46-2ce197b4d402",
"question": "What is your name?",
"answer": "I am Dify.",
"hit_count": 0,
"created_at": 1735625869
}
```
</CodeGroup>
---
## PUT /apps/annotations/:annotation_id Update Annotation
### Path Parameters
- `annotation_id` (string): Annotation ID.
### Request Body
- `question` (string, optional): Question.
- `answer` (string, optional): Answer.
<CodeGroup>
```bash cURL
curl --location --request PUT 'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"question": "What is your full name?",
"answer": "I am Dify, your AI assistant."
}'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"id": "{annotation_id}",
"question": "What is your full name?",
"answer": "I am Dify, your AI assistant.",
"hit_count": 0,
"created_at": 1735625869
}
```
</CodeGroup>
---
## DELETE /apps/annotations/:annotation_id Delete Annotation
### Path Parameters
- `annotation_id` (string): Annotation ID.
### Response
- `204 No Content`
<CodeGroup>
```bash cURL curl --location --request DELETE
'https://api.dify.ai/v1/apps/annotations/{annotation_id}' \ --header
'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>```text Response 204 No Content ```</CodeGroup>
---
## POST /apps/annotation-reply/:action Initial Annotation Reply Settings
### Path Parameters
- `action` (string): Action, can only be `enable` or `disable`.
### Request Body
- `embedding_model_provider` (string, optional): Specified embedding model provider. Must be set up in the system.
- `embedding_model` (string, optional): Specified embedding model.
- `score_threshold` (number, optional): Similarity threshold for matching annotated replies. Only annotations with scores above this threshold will be recalled. (Required if enabling)
**Note:** The provider and model name of the embedding model can be obtained through `v1/workspaces/current/models/model-types/text-embedding`. (Requires Dataset API Token for that endpoint).
<CodeGroup>
```bash "Enable with specific model"
curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/enable' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"score_threshold": 0.9,
"embedding_model_provider": "zhipu",
"embedding_model": "embedding_3"
}'
```
```bash "Disable"
curl --location --request POST 'https://api.dify.ai/v1/apps/annotation-reply/disable' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json'
```
</CodeGroup>
<CodeGroup>
```json Response
{
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
"job_status": "waiting"
}
```
This interface is executed asynchronously. Query the job status interface to get the final result.
</CodeGroup>
---
## GET /apps/annotation-reply/:action/status/:job_id Query Initial Annotation Reply Settings Task Status
### Path Parameters
- `action` (string): Action, `enable` or `disable`. Must match the action in the initial settings call.
- `job_id` (string): Job ID from the initial settings call.
<CodeGroup>
```bash cURL curl --location --request GET
'https://api.dify.ai/v1/apps/annotation-reply/enable/status/{job_id}' \
--header 'Authorization: Bearer {YOUR_API_KEY}' ```
</CodeGroup>
<CodeGroup>
```json Response
{
"job_id": "b15c8f68-1cf4-4877-bf21-ed7cf2011802",
"job_status": "succeeded", // or "waiting", "processing", "failed"
"error_msg": "" // Contains error message if job_status is "failed"
}
```
</CodeGroup>
{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}
<CardGroup cols="2">
<Card
title="Edit this page"
icon="pen-to-square"
href="https://github.com/langgenius/dify-docs-mintlify/edit/main/api_access/chat.en.mdx"
>
Help improve our documentation by contributing directly
</Card>
<Card
title="Report an issue"
icon="github"
href="https://github.com/langgenius/dify-docs-mintlify/issues/new?title=Documentation%20Issue%3A%20&body=%23%23%20Issue%20Description%0A%3C%21--%20Please%20briefly%20describe%20the%20issue%20you%20found%20--%3E%0A%0A%23%23%20Page%20Link%0Ahttps%3A%2F%2Fgithub.com%2Flanggenius%2Fdify-docs-mintlify%2Fblob%2Fmain%2Fapi_access%2Fchat.en.mdx%0A%0A%23%23%20Suggested%20Changes%0A%3C%21--%20If%20you%20have%20specific%20suggestions%20for%20changes%2C%20please%20describe%20them%20here%20--%3E%0A%0A%3C%21--%20Thank%20you%20for%20helping%20improve%20our%20documentation%21%20--%3E"
>
Found an error or have suggestions? Let us know
</Card>
</CardGroup>
Reference in New Issue View Git Blame Copy Permalink