Dify chat messages, conversations, and feedback

Use this family to read chat history, suggestions, conversations, feedback, and conversation variables. It also supports feedback, rename, variable-update, and conversation-deletion mutations under AIP approval and replay controls.

Most operations require a chat-like Dify application and one stable end-user identity. Application-wide feedback is the exception. It has no end-user input and is projected for every configured app mode.

Choose an operation

The four chat-like connector modes are chat, advanced-chat, agent-chat, and agent. At the pinned Dify revision, conversation-variable routes accept only the first three. Connector discovery still projects both variable operations for agent, so do not invoke them for that mode.

The capability template is:

cap:dify:<app_id>:<operation>

Obtain the exact capability ID from tenant discovery. A capability exposed for one app does not authorize access to another app or another end user.

Partition the Action input

Each rendered path value contains 1 to 512 bytes without control characters. The connector accepts a bounded string, while the pinned provider routes parse message, conversation, and variable path values as UUIDs.

user contains 1 to 256 bytes without control characters. The connector inserts it into the required query or body location. A conflicting provider user value is rejected before dispatch.

query has at most 128 keys. Each name contains 1 to 256 bytes, and each value is a scalar or an array of at most 256 scalars. body has at most 512 properties, and its encoded JSON cannot exceed 8 MiB.

Read messages and suggestions

List one user’s messages by selecting message.list and passing the provider conversation ID in query:

{
  "user": "tenant-user-0190",
  "query": {
    "conversation_id": "0190c42f-2d5a-7000-8000-000000000101",
    "limit": 20
  }
}

The pinned provider requires conversation_id. first_id is an optional message cursor, and limit ranges from 1 to 100 with a default of 20. The first page returns the latest messages; the next request uses the first retained message ID to fetch older records.

Use message.suggested.get with a UUID message_id and the same user value. The provider can reject the read when the message is absent or suggested questions are disabled.

Read application feedback

feedback.list reads feedback across the selected application rather than one end user. Its provider query accepts page from 1 upward and limit from 1 to 101. Both default to 1 and 20 respectively.

The returned records can identify conversations, messages, end users, or accounts. Treat the result as confidential PII even though the request has no user field.

Read conversations and variables

conversation.list accepts optional last_id, limit, and sort_by query fields. limit ranges from 1 to 100 and defaults to 20. sort_by is one of created_at, -created_at, updated_at, or -updated_at.

conversation.variable.list requires a UUID conversation_id. Its query can carry last_id, a limit from 1 to 100, and variable_name. The name contains 1 to 255 safe alphanumeric, hyphen, underscore, or period characters.

Conversation and variable reads are end-user scoped. A valid app key does not permit one user value to read another user’s conversation state.

Apply the four mutations

Every mutation requires tenant-policy approval and one non-blank Action idempotency key of at most 512 bytes. The connector sends the key to Dify and retains a tenant-scoped AIP reservation for 24 hours. This does not prove that the provider deduplicates a repeated external effect.

Submit or replace message feedback with message.feedback.create:

{
  "message_id": "0190c42f-2d5a-7000-8000-000000000102",
  "user": "tenant-user-0190",
  "body": {
    "rating": "like",
    "content": "The answer resolved the task."
  }
}

The pinned provider accepts like, dislike, or null for rating; null revokes earlier feedback. content is optional.

The other mutation bodies are:

Delete is irreversible through this connector. Rename and variable update also declare no rollback capability. Verify the exact conversation, user, and variable before approval.

Interpret the result

A successful JSON operation completes with the generic connector envelope:

{
  "http_status": 200,
  "body": {
    "result": "success"
  },
  "content_type": "application/json",
  "provider_request_id": null
}

The nested body follows the selected pinned Dify route. A non-success provider status becomes a typed connector error instead of a completed envelope.

All nine operations are synchronous and do not publish streaming or capability-specific cancellation. Results, query values, feedback, messages, and variables carry confidential data with PII and redaction requirements.

Recover safely

None of the four mutations publishes safe retry support. Preserve the original Action ID, input, key, approval, provider request identity, and final read used to settle the outcome.

Related documentation

• Dify capability index
• Dify connector overview
• Dify connector configuration
• Authentication and credential scopes
• Errors and retry decisions