Setup Guide — Dify Chat

This static page talks directly from your browser to your Dify 1.16 Service API endpoint. It does not proxy messages through this site. You need a published app and an app API key.

1. Create a connection

  1. In Dify, publish your chatflow, workflow, chatbot, or agent app and copy its app API key.
  2. Open Dify Chat and select + Add connection.
  3. Enter a label, the Service API base URL, and the API key.
  4. Choose the payload type:
  5. Select Test. A successful test verifies the endpoint and key via GET /parameters.
Dify documents app API keys as secrets. This app stores them only in this browser’s localStorage, but on a shared computer anyone with browser access may read them. Do not use a shared/browser profile you do not control.

2. Input parameters

Dify apps declare their own input variables. Those names and types come from your app’s user_input_form/variables, not from this UI. Add one row per variable:

The rows become the top-level inputs object. The text you type in the message box is sent as query for chat apps, and as inputs.query for workflow runs.

3. Response mode

Dify accepts response_mode: "blocking" and response_mode: "streaming".

Dify documents that Agent apps support streaming only; a blocking request to an Agent app returns HTTP 400. See: Send chat message API.

4. File upload — exact flow

Dify requires two steps for local files. One upload call accepts one file, so the app uploads up to 10 files sequentially and then references all returned IDs in the conversation payload.

Step 4.1 — Upload each file

POST /v1/files/upload
Authorization: Bearer <API_KEY>
Content-Type: multipart/form-data

file:   <binary file, one file per request>
user:   <same user id used by the chat/workflow request>

Example from the Dify docs:

curl -X POST 'https://api.dify.ai/v1/files/upload' \
  -H 'Authorization: Bearer {API_KEY}' \
  -F 'file=@product-photo.png;type=image/png' \
  -F 'user=user-123'

The response is HTTP 201 and includes id, name, size, extension, mime_type, source_url, and other metadata. This app uses the returned id.

Dify documents these constraints: the filename must not contain / or \; the MIME type must be present; default limits are images 10 MB, audio 50 MB, video 100 MB, other files 15 MB. Self-hosted limits can be changed with UPLOAD_*_FILE_SIZE_LIMIT variables. File types actually consumed depend on the app’s file-upload settings; check GET /parameters. See: Upload File API.

Step 4.2 — Put the returned ID into the conversation payload

For chat apps, Dify documents files at the same level as query, user, inputs, response_mode, and conversation_id:

{
  "query": "Summarise the attached document",
  "user": "dify-chat-web",
  "inputs": {},
  "response_mode": "streaming",
  "conversation_id": "<optional; omit for new chat>",
  "files": [
    {
      "type": "document",
      "transfer_method": "local_file",
      "upload_file_id": "<id returned by /files/upload>"
    }
  ]
}

Dify documents files[] requires type and transfer_method; upload_file_id is required when transfer_method is local_file. Allowed types: image, document, audio, video, custom. Source: Send chat message API.

Why we do not put files directly inside inputs: Dify documents both mechanisms. The top-level files array is the documented "file list" mechanism suitable when files accompany text and the model supports vision. File-type variables can also be placed under inputs.<file_variable> as arrays of file objects. This UI currently uses the top-level files mechanism because it matches the documented request shape for chat messages and is available for workflow runs as well. Source: Run workflow API.

Workflow payload shape

{
  "inputs": {
    "query": "Translate this to French: Hello world",
    "your_other_variable": "value"
  },
  "user": "dify-chat-web",
  "response_mode": "blocking",
  "files": [
    { "type": "document", "transfer_method": "local_file", "upload_file_id": "<id>" }
  ]
}

Important: the Dify workflow API documents query as an example variable inside inputs; there is no documented top-level query or conversation_id request field for /workflows/run. The app therefore does not inject a hidden conversation_id into workflow inputs unless you explicitly declare a variable with that name. Source: Run workflow API.

5. Conversation continuity

For chat apps, Dify returns conversation_id in the blocking response and in SSE events. This app saves it per chat and sends it back on the next turn. Omit it or pass an empty string to start a new chat; use Reset conversation in the UI. Workflow runs do not have a documented top-level conversation_id request field.

6. Response fields and citations

Apps return different response shapes. This app prefers these owner-specified locations first:

App typeLocationFields
Chatflowanswerresponse_with_citations_ui, stringified_citations
Workflowdataresponse_with_citations, stringified_citations

If none of these is found, the app flattens the entire response payload and lists every leaf field in the selector under the response. Choose the field that contains the text to display. The selected field is also what Markdown/Word export uses.

7. Queue

Enter a message and press Send again even while a reply is in progress. Up to 10 messages can be queued per chat. Each queued turn captures the input parameters and files at enqueue time, then waits for the prior Dify response before sending. A failed response is shown as an error and the queue continues.

8. Live test checklist

API documentation

Back to chat · Privacy · Source download