[DOCS]: Persistent Storage documentation is a bit unclear what self is in the code example #258

New Issue

2026-02-16T05:19:37-05:00

yindo commented

2026-02-16 05:19:37 -05:00

Originally created by @Escapingbug on GitHub (Oct 28, 2025).

Type of Documentation Change

Other

Documentation Page URL or Path

https://docs.dify.ai/plugin-dev-en/0411-persistent-storage-kv

Current Content

Current code example gives entry point and usage such as:

Entry point:

    self.session.storage

Interface:

    def set(self, key: str, val: bytes) -> None:
        pass

Suggested Changes

The code example should include a bit more context such as what the self is mean to be.
It is better to describe what the selfs are about, and better write down code examples to help user understand how it can be used.

Reason for Change

Considering the context of plugin development, there are at least provider context and tool context. Although it is possible that both provider and tool contexts support the storage accessing, it is unclear in the example.
Also, the interface set references self as well, which confuses reader even more. It is possible to be used directly on tool context for example self.set(xxx) or self.session.storage.set(xxx).
It is better to describe this directly. If it is possible to provide code examples, which would be better.

Code of Conduct

I agree to follow Dify's documentation contribution guidelines
I have searched for existing issues search for existing issues, including closed ones.
I confirm that I am using English to submit this report, otherwise it will be closed.
【中文用户 & Non English User】请使用英语提交，否则会被关闭：）
Please do not modify this template :) and fill in all the required fields.

Originally created by @Escapingbug on GitHub (Oct 28, 2025). ### Type of Documentation Change Other ### Documentation Page URL or Path https://docs.dify.ai/plugin-dev-en/0411-persistent-storage-kv ### Current Content Current code example gives entry point and usage such as: Entry point: ```python self.session.storage ``` Interface: ```python def set(self, key: str, val: bytes) -> None: pass ``` ### Suggested Changes The code example should include a bit more context such as what the `self` is mean to be. It is better to describe what the `self`s are about, and better write down code examples to help user understand how it can be used. ### Reason for Change Considering the context of plugin development, there are at least provider context and tool context. Although it is possible that both provider and tool contexts support the storage accessing, it is unclear in the example. Also, the interface `set` references `self` as well, which confuses reader even more. It is possible to be used directly on tool context for example `self.set(xxx)` or `self.session.storage.set(xxx)`. It is better to describe this directly. If it is possible to provide code examples, which would be better. ### Code of Conduct - [x] I agree to follow Dify's documentation [contribution guidelines](https://github.com/langgenius/dify/blob/0277a37fcad5ad86aeb239485c27fffd5cd90043/CONTRIBUTING.md) - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report, otherwise it will be closed. - [x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭：） - [x] Please do not modify this template :) and fill in all the required fields.

yindo added the documentation label 2026-02-16 05:19:37 -05:00

yindo closed this issue

2026-02-16 05:19:37 -05:00

yindo commented

2026-02-16 05:19:38 -05:00

@dosubot[bot] commented on GitHub (Oct 28, 2025):

Hi @Escapingbug! I'm Dosu and I’m helping the dify-docs team.

In the Dify plugin persistent storage examples, self refers to the instance of your plugin endpoint handler class, which is typically a subclass of the plugin SDK's Endpoint class. Persistent storage is accessed via self.session.storage within your plugin class methods. For example, in the official WhatsApp Bot plugin, you see usage like:

class WhatsappBotEndpoint(Endpoint):
    def _invoke_app_reply(self, app_id, query, identify_inputs, conversation_key):
        # Retrieve a value from storage
        raw = self.session.storage.get(conversation_key)
        # Store a value in storage
        self.session.storage.set(conversation_key, str(new_conversation_id).encode("utf-8"))

This means self is not a provider or tool context, but specifically your plugin handler instance. The session attribute provides access to the storage interface, supporting get, set, and delete methods. For more context, see the official plugin example.

Clarifying this in the documentation and providing a full code snippet like above would help developers understand how to use persistent storage in their plugins.

To reply, just mention @dosu.

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

@dosubot[bot] commented on GitHub (Oct 28, 2025):  Hi @Escapingbug! I'm [Dosu](https://go.dosu.dev/dosubot) and I’m helping the dify-docs team.  In the Dify plugin persistent storage examples, `self` refers to the instance of your plugin endpoint handler class, which is typically a subclass of the plugin SDK's `Endpoint` class. Persistent storage is accessed via `self.session.storage` within your plugin class methods. For example, in the official WhatsApp Bot plugin, you see usage like: ```python class WhatsappBotEndpoint(Endpoint): def _invoke_app_reply(self, app_id, query, identify_inputs, conversation_key): # Retrieve a value from storage raw = self.session.storage.get(conversation_key) # Store a value in storage self.session.storage.set(conversation_key, str(new_conversation_id).encode("utf-8")) ``` This means `self` is not a provider or tool context, but specifically your plugin handler instance. The `session` attribute provides access to the storage interface, supporting `get`, `set`, and `delete` methods. For more context, see the [official plugin example](https://github.com/langgenius/dify-official-plugins/blob/2b396d0b200fd6f963f2fb1c32133fcaef1615fb/tools/whatsapp-bot/endpoints/whatsapp-bot.py). Clarifying this in the documentation and providing a full code snippet like above would help developers understand how to use persistent storage in their plugins.  *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/612c2668-906e-42ab-af6a-17d2ce07fc6c?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/612c2668-906e-42ab-af6a-17d2ce07fc6c?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/612c2668-906e-42ab-af6a-17d2ce07fc6c?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/612c2668-906e-42ab-af6a-17d2ce07fc6c?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/612c2668-906e-42ab-af6a-17d2ce07fc6c?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/612c2668-906e-42ab-af6a-17d2ce07fc6c?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/612c2668-906e-42ab-af6a-17d2ce07fc6c?feedback_type=other)</sup>  [![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot) [![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/501)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: langgenius/dify-docs#258

[DOCS]: Persistent Storage documentation is a bit unclear what self is in the code example #258