General Discussion

[imkiven]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

Content

How to set systemVariables when embedding a web page in <iframe>

[dosubot[bot]]

Hi @imkiven! I'm Dosu and I’m helping the dify team.

To set systemVariables when embedding a Dify app in an <iframe>, pass them as URL parameters prefixed with sys. (for example, sys.user_id, sys.conversation_id). Each value must be gzip-compressed, Base64-encoded, and URI-encoded before appending to the iframe src URL. Here’s a practical JavaScript example for encoding:

import pako from 'pako';

function encodeValue(value) {
  const uint8Array = new TextEncoder().encode(value);
  const gzipped = pako.gzip(uint8Array);
  const base64 = btoa(String.fromCharCode(...gzipped));
  return encodeURIComponent(base64);
}

// Usage:
const encodedUserId = encodeValue('your_user_id');
const iframeUrl = `https://your-dify-host/chatbot/{token}?sys.user_id=${encodedUserId}`;

You can use any key with the sys. prefix, but values must be valid for your app (for example, a valid UUID for conversation_id). The same encoding applies to other systemVariables like sys.ref_email or business tickets. User variables use the user. prefix and inputs do not require a prefix.

Keep the total URL length under 2048 characters to avoid loading issues. Do not pass secrets or sensitive data via URL parameters—these are exposed to browser history and inspection. Use HTTPS for transport security, but remember this does not protect against exposure in logs or browser tools. For more details, see the official documentation and embed.js implementation.

To reply, just mention @dosu.

---

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

[imkiven]

一般的参数可以传递过去，但是系统内置的sys.XXX无法传递

[dosubot[bot]]

你说得对，普通参数可以通过 iframe 传递，但内置的 sys.XXX 系统变量（比如 sys.user_id）通常无法生效，原因在于 Dify 后端只会识别和处理一小部分明确允许的 sys.XXX 变量，其他的即使传递了也会被忽略。这是后端安全和设计上的限制，防止任意系统级变量被注入。只有像 user.XXX 这样的用户变量可以自定义传递并被前端和后端识别。

如果你确实需要传递 sys.XXX 变量，当前只能用 Dify 已经支持的那几个（比如 sys.user_id），并且要用 gzip+base64+urlencode 方式编码。如果你发现 sys.user_id 也无法生效，建议检查 iframe URL 拼接和编码方式是否完全符合官方要求（参考1）。

如果你想传递自定义的系统变量，目前没有官方支持，只能通过修改后端代码来实现（比如在后端 controller 里显式解析和允许你需要的 sys.XXX 变量）参考2。

总结：普通参数和 user.XXX 可以直接传递，sys.XXX 只有极少数被后端硬编码允许，其他的会被忽略。这是 Dify 的设计限制。

To reply, just mention @dosu.

---

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