{
  "schemaVersion": "1.0",
  "title": "Dify chat messages, conversations, and feedback",
  "description": "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.",
  "canonical": "https://getaip.org/docs/connectors/dify/capabilities/chat-messages-conversations-and-feedback",
  "route": "/docs/connectors/dify/capabilities/chat-messages-conversations-and-feedback",
  "source": "docs/connectors/dify/capabilities/chat-messages-conversations-and-feedback.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/dify/capabilities/chat-messages-conversations-and-feedback.md",
    "txt": "/docs/download/connectors/dify/capabilities/chat-messages-conversations-and-feedback.txt",
    "json": "/docs/download/connectors/dify/capabilities/chat-messages-conversations-and-feedback.json",
    "pdf": "/docs/download/connectors/dify/capabilities/chat-messages-conversations-and-feedback.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dify chat messages, conversations, and feedback\ndescription: >-\n  Read chat history and conversation state, then govern feedback, rename,\n  variable-update, and deletion mutations through the frozen Dify connector\nkind: capability-reference\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: dify\n---\n\n# Dify chat messages, conversations, and feedback\n\nUse this family to read chat history, suggestions, conversations, feedback, and\nconversation variables. It also supports feedback, rename, variable-update,\nand conversation-deletion mutations under AIP approval and replay controls.\n\nMost operations require a chat-like Dify application and one stable end-user\nidentity. Application-wide feedback is the exception. It has no end-user input\nand is projected for every configured app mode.\n\n## Choose an operation\n\n| Operation suffix | Method and route | Identity input | Connector projection | Policy |\n|---|---|---|---|---|\n| `message.list` | `GET /v1/messages` | `user` in query | Four chat-like modes | Low-risk read; retry supported |\n| `message.feedback.create` | `POST /v1/messages/{message_id}/feedbacks` | `user` in JSON | Four chat-like modes | Medium mutation; approval and key required |\n| `feedback.list` | `GET /v1/app/feedbacks` | None | All six app modes | Low-risk read; retry supported |\n| `message.suggested.get` | `GET /v1/messages/{message_id}/suggested` | `user` in query | Four chat-like modes | Low-risk read; retry supported |\n| `conversation.list` | `GET /v1/conversations` | `user` in query | Four chat-like modes | Low-risk read; retry supported |\n| `conversation.delete` | `DELETE /v1/conversations/{conversation_id}` | `user` in JSON | Four chat-like modes | High mutation; approval and key required |\n| `conversation.rename` | `POST /v1/conversations/{conversation_id}/name` | `user` in JSON | Four chat-like modes | Medium mutation; approval and key required |\n| `conversation.variable.list` | `GET /v1/conversations/{conversation_id}/variables` | `user` in query | See mode boundary below | Low-risk read; retry supported |\n| `conversation.variable.update` | `PUT /v1/conversations/{conversation_id}/variables/{variable_id}` | `user` in JSON | See mode boundary below | Medium mutation; approval and key required |\n\nThe four chat-like connector modes are `chat`, `advanced-chat`, `agent-chat`,\nand `agent`. At the pinned Dify revision, conversation-variable routes accept\nonly the first three. Connector discovery still projects both variable\noperations for `agent`, so do not invoke them for that mode.\n\nThe capability template is:\n\n```text\ncap:dify:<app_id>:<operation>\n```\n\nObtain the exact capability ID from tenant discovery. A capability exposed for\none app does not authorize access to another app or another end user.\n\n## Partition the Action input\n\n| Input field | Connector behavior |\n|---|---|\n| `message_id` | Renders one message route segment |\n| `conversation_id` | Renders one conversation route segment or enters a provider query |\n| `variable_id` | Renders one conversation-variable route segment |\n| `user` | Enters the query for user-scoped reads and JSON for mutations |\n| `query` | Supplies bounded provider query fields |\n| `body` | Supplies bounded provider JSON fields |\n\nEach rendered path value contains 1 to 512 bytes without control characters.\nThe connector accepts a bounded string, while the pinned provider routes parse\nmessage, conversation, and variable path values as UUIDs.\n\n`user` contains 1 to 256 bytes without control characters. The connector\ninserts it into the required query or body location. A conflicting provider\n`user` value is rejected before dispatch.\n\n`query` has at most 128 keys. Each name contains 1 to 256 bytes, and each value\nis a scalar or an array of at most 256 scalars. `body` has at most 512\nproperties, and its encoded JSON cannot exceed 8 MiB.\n\n## Read messages and suggestions\n\nList one user's messages by selecting `message.list` and passing the provider\nconversation ID in `query`:\n\n```json\n{\n  \"user\": \"tenant-user-0190\",\n  \"query\": {\n    \"conversation_id\": \"0190c42f-2d5a-7000-8000-000000000101\",\n    \"limit\": 20\n  }\n}\n```\n\nThe pinned provider requires `conversation_id`. `first_id` is an optional\nmessage cursor, and `limit` ranges from 1 to 100 with a default of 20. The first\npage returns the latest messages; the next request uses the first retained\nmessage ID to fetch older records.\n\nUse `message.suggested.get` with a UUID `message_id` and the same `user` value.\nThe provider can reject the read when the message is absent or suggested\nquestions are disabled.\n\n## Read application feedback\n\n`feedback.list` reads feedback across the selected application rather than one\nend user. Its provider query accepts `page` from 1 upward and `limit` from 1 to\n101. Both default to 1 and 20 respectively.\n\nThe returned records can identify conversations, messages, end users, or\naccounts. Treat the result as confidential PII even though the request has no\n`user` field.\n\n## Read conversations and variables\n\n`conversation.list` accepts optional `last_id`, `limit`, and `sort_by` query\nfields. `limit` ranges from 1 to 100 and defaults to 20. `sort_by` is one of\n`created_at`, `-created_at`, `updated_at`, or `-updated_at`.\n\n`conversation.variable.list` requires a UUID `conversation_id`. Its query can\ncarry `last_id`, a limit from 1 to 100, and `variable_name`. The name contains\n1 to 255 safe alphanumeric, hyphen, underscore, or period characters.\n\nConversation and variable reads are end-user scoped. A valid app key does not\npermit one `user` value to read another user's conversation state.\n\n## Apply the four mutations\n\nEvery mutation requires tenant-policy approval and one non-blank Action\nidempotency key of at most 512 bytes. The connector sends the key to Dify and\nretains a tenant-scoped AIP reservation for 24 hours. This does not prove that\nthe provider deduplicates a repeated external effect.\n\nSubmit or replace message feedback with `message.feedback.create`:\n\n```json\n{\n  \"message_id\": \"0190c42f-2d5a-7000-8000-000000000102\",\n  \"user\": \"tenant-user-0190\",\n  \"body\": {\n    \"rating\": \"like\",\n    \"content\": \"The answer resolved the task.\"\n  }\n}\n```\n\nThe pinned provider accepts `like`, `dislike`, or `null` for `rating`; `null`\nrevokes earlier feedback. `content` is optional.\n\nThe other mutation bodies are:\n\n| Operation | Required provider body |\n|---|---|\n| `conversation.delete` | No field beyond the connector-inserted `user` |\n| `conversation.rename` | Non-blank `name`, or `auto_generate: true` |\n| `conversation.variable.update` | `value` matching the variable's declared type |\n\nDelete is irreversible through this connector. Rename and variable update also\ndeclare no rollback capability. Verify the exact conversation, user, and\nvariable before approval.\n\n## Interpret the result\n\nA successful JSON operation completes with the generic connector envelope:\n\n```json\n{\n  \"http_status\": 200,\n  \"body\": {\n    \"result\": \"success\"\n  },\n  \"content_type\": \"application/json\",\n  \"provider_request_id\": null\n}\n```\n\nThe nested `body` follows the selected pinned Dify route. A non-success provider\nstatus becomes a typed connector error instead of a completed envelope.\n\nAll nine operations are synchronous and do not publish streaming or\ncapability-specific cancellation. Results, query values, feedback, messages,\nand variables carry confidential data with PII and redaction requirements.\n\n## Recover safely\n\n| Observation | Decision |\n|---|---|\n| Read input is rejected before dispatch | Correct the path, user, query, or body under the same task decision |\n| Variable operation on `agent` is rejected | Do not retry; use a supported app mode or remove the unsupported call |\n| Message or conversation is absent | Re-establish the exact app, user, and UUID before another request |\n| Read fails with a verified retryable error | Retry only within the declared Action budget |\n| Mutation remains pending approval | Decide the same immutable Action and input |\n| Mutation fails before provider dispatch | Correct the rejected input without claiming an external effect |\n| Mutation response is lost or transport-ambiguous | Treat provider outcome as uncertain and inspect authoritative Dify state |\n| Delete outcome cannot be established | Escalate; do not create a replacement delete Action |\n| Returned data crosses an app or user boundary | Stop traffic and treat the event as an isolation incident |\n\nNone of the four mutations publishes safe retry support. Preserve the original\nAction ID, input, key, approval, provider request identity, and final read used\nto settle the outcome.\n\n## Related documentation\n\n- [Dify capability index](README.md)\n- [Dify connector overview](../README.md)\n- [Dify connector configuration](../reference/configuration.md)\n- [Authentication and credential scopes](../getting-started/authentication-and-credential-scopes.md)\n- [Errors and retry decisions](../../../reference/errors.md)\n",
    "text": "Dify chat messages, conversations, and feedback\n\nUse this family to read chat history, suggestions, conversations, feedback, and\nconversation variables. It also supports feedback, rename, variable-update,\nand conversation-deletion mutations under AIP approval and replay controls.\n\nMost operations require a chat-like Dify application and one stable end-user\nidentity. Application-wide feedback is the exception. It has no end-user input\nand is projected for every configured app mode.\n\nChoose an operation\n\n| Operation suffix | Method and route | Identity input | Connector projection | Policy |\n\n| message.list | GET /v1/messages | user in query | Four chat-like modes | Low-risk read; retry supported |\n| message.feedback.create | POST /v1/messages/{messageid}/feedbacks | user in JSON | Four chat-like modes | Medium mutation; approval and key required |\n| feedback.list | GET /v1/app/feedbacks | None | All six app modes | Low-risk read; retry supported |\n| message.suggested.get | GET /v1/messages/{messageid}/suggested | user in query | Four chat-like modes | Low-risk read; retry supported |\n| conversation.list | GET /v1/conversations | user in query | Four chat-like modes | Low-risk read; retry supported |\n| conversation.delete | DELETE /v1/conversations/{conversationid} | user in JSON | Four chat-like modes | High mutation; approval and key required |\n| conversation.rename | POST /v1/conversations/{conversationid}/name | user in JSON | Four chat-like modes | Medium mutation; approval and key required |\n| conversation.variable.list | GET /v1/conversations/{conversationid}/variables | user in query | See mode boundary below | Low-risk read; retry supported |\n| conversation.variable.update | PUT /v1/conversations/{conversationid}/variables/{variableid} | user in JSON | See mode boundary below | Medium mutation; approval and key required |\n\nThe four chat-like connector modes are chat, advanced-chat, agent-chat,\nand agent. At the pinned Dify revision, conversation-variable routes accept\nonly the first three. Connector discovery still projects both variable\noperations for agent, so do not invoke them for that mode.\n\nThe capability template is:\n\ncap:dify::\n\nObtain the exact capability ID from tenant discovery. A capability exposed for\none app does not authorize access to another app or another end user.\n\nPartition the Action input\n\n| Input field | Connector behavior |\n\n| messageid | Renders one message route segment |\n| conversationid | Renders one conversation route segment or enters a provider query |\n| variableid | Renders one conversation-variable route segment |\n| user | Enters the query for user-scoped reads and JSON for mutations |\n| query | Supplies bounded provider query fields |\n| body | Supplies bounded provider JSON fields |\n\nEach rendered path value contains 1 to 512 bytes without control characters.\nThe connector accepts a bounded string, while the pinned provider routes parse\nmessage, conversation, and variable path values as UUIDs.\n\nuser contains 1 to 256 bytes without control characters. The connector\ninserts it into the required query or body location. A conflicting provider\nuser value is rejected before dispatch.\n\nquery has at most 128 keys. Each name contains 1 to 256 bytes, and each value\nis a scalar or an array of at most 256 scalars. body has at most 512\nproperties, and its encoded JSON cannot exceed 8 MiB.\n\nRead messages and suggestions\n\nList one user's messages by selecting message.list and passing the provider\nconversation ID in query:\n\n{\n  \"user\": \"tenant-user-0190\",\n  \"query\": {\n    \"conversationid\": \"0190c42f-2d5a-7000-8000-000000000101\",\n    \"limit\": 20\n  }\n}\n\nThe pinned provider requires conversationid. firstid is an optional\nmessage cursor, and limit ranges from 1 to 100 with a default of 20. The first\npage returns the latest messages; the next request uses the first retained\nmessage ID to fetch older records.\n\nUse message.suggested.get with a UUID messageid and the same user value.\nThe provider can reject the read when the message is absent or suggested\nquestions are disabled.\n\nRead application feedback\n\nfeedback.list reads feedback across the selected application rather than one\nend user. Its provider query accepts page from 1 upward and limit from 1 to\n101. Both default to 1 and 20 respectively.\n\nThe returned records can identify conversations, messages, end users, or\naccounts. Treat the result as confidential PII even though the request has no\nuser field.\n\nRead conversations and variables\n\nconversation.list accepts optional lastid, limit, and sortby query\nfields. limit ranges from 1 to 100 and defaults to 20. sortby is one of\ncreatedat, -createdat, updatedat, or -updatedat.\n\nconversation.variable.list requires a UUID conversationid. Its query can\ncarry lastid, a limit from 1 to 100, and variablename. The name contains\n1 to 255 safe alphanumeric, hyphen, underscore, or period characters.\n\nConversation and variable reads are end-user scoped. A valid app key does not\npermit one user value to read another user's conversation state.\n\nApply the four mutations\n\nEvery mutation requires tenant-policy approval and one non-blank Action\nidempotency key of at most 512 bytes. The connector sends the key to Dify and\nretains a tenant-scoped AIP reservation for 24 hours. This does not prove that\nthe provider deduplicates a repeated external effect.\n\nSubmit or replace message feedback with message.feedback.create:\n\n{\n  \"messageid\": \"0190c42f-2d5a-7000-8000-000000000102\",\n  \"user\": \"tenant-user-0190\",\n  \"body\": {\n    \"rating\": \"like\",\n    \"content\": \"The answer resolved the task.\"\n  }\n}\n\nThe pinned provider accepts like, dislike, or null for rating; null\nrevokes earlier feedback. content is optional.\n\nThe other mutation bodies are:\n\n| Operation | Required provider body |\n\n| conversation.delete | No field beyond the connector-inserted user |\n| conversation.rename | Non-blank name, or autogenerate: true |\n| conversation.variable.update | value matching the variable's declared type |\n\nDelete is irreversible through this connector. Rename and variable update also\ndeclare no rollback capability. Verify the exact conversation, user, and\nvariable before approval.\n\nInterpret the result\n\nA successful JSON operation completes with the generic connector envelope:\n\n{\n  \"httpstatus\": 200,\n  \"body\": {\n    \"result\": \"success\"\n  },\n  \"contenttype\": \"application/json\",\n  \"providerrequestid\": null\n}\n\nThe nested body follows the selected pinned Dify route. A non-success provider\nstatus becomes a typed connector error instead of a completed envelope.\n\nAll nine operations are synchronous and do not publish streaming or\ncapability-specific cancellation. Results, query values, feedback, messages,\nand variables carry confidential data with PII and redaction requirements.\n\nRecover safely\n\n| Observation | Decision |\n\n| Read input is rejected before dispatch | Correct the path, user, query, or body under the same task decision |\n| Variable operation on agent is rejected | Do not retry; use a supported app mode or remove the unsupported call |\n| Message or conversation is absent | Re-establish the exact app, user, and UUID before another request |\n| Read fails with a verified retryable error | Retry only within the declared Action budget |\n| Mutation remains pending approval | Decide the same immutable Action and input |\n| Mutation fails before provider dispatch | Correct the rejected input without claiming an external effect |\n| Mutation response is lost or transport-ambiguous | Treat provider outcome as uncertain and inspect authoritative Dify state |\n| Delete outcome cannot be established | Escalate; do not create a replacement delete Action |\n| Returned data crosses an app or user boundary | Stop traffic and treat the event as an isolation incident |\n\nNone of the four mutations publishes safe retry support. Preserve the original\nAction ID, input, key, approval, provider request identity, and final read used\nto settle the outcome.\n\nRelated documentation\n• Dify capability index (README.md)\n• Dify connector overview (../README.md)\n• Dify connector configuration (../reference/configuration.md)\n• Authentication and credential scopes (../getting-started/authentication-and-credential-scopes.md)\n• Errors and retry decisions (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "602f828b957a54066fde85f07384283e7c7f22b4550549b98cb1713518a597d0"
  }
}