Conversation history when using iframe

[dapicester]

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

Hi, I am using the iframe to embed amy workflow in my website. I am using the full iframe, not the balloon.

I want to persist the conversations if I open my website on my laptop and my mobile. That is, when I open my website on my mobile phone I should see the conversation history as it happened on my laptop.

I understand that I need to pass user_id and conversation_id obtained from Dify as querystring parameters of the iframe src attibute, properly encoded, gzipped and base64 encoded. I am doing that and I can see those correctly set Dify.

The HTML snippet looks like this:

<iframe
 src="http://example.com/chatbot/workflow_id?user_id=encodedvalue&conversation_id=encodedvalue"
 style="width: 100%; height: 100%; min-height: 700px"
 frameborder="0"
 allow="microphone">
</iframe>

The first time I open the iframe the user_id is my internal ID, and conversation_id is empty.
The workflow calls my API so I can store sys.conversation_id.

The second time I open the iframe conversation_id has now the value Dify sent, which looks like a uuid.

The problem is that Dify is not showing the chat history when I open the iframe on the second device.

Am I missing something? I am not sure if this is a bug, or if I pass the querystring param as sys.conversation_id or conversation_id.

[dosubot[bot]]

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

To persist conversation history across devices when embedding Dify via iframe, you should:

• Pass the user ID as the sys.user_id parameter (GZIP-compressed, Base64-encoded, and URI-encoded), and the conversation ID as conversation_id (not sys.conversation_id) in the iframe URL. For example: ...?sys.user_id=ENCODED_USER_ID&conversation_id=UUID reference.
• On the first load, omit conversation_id so Dify generates a new one. Store the returned conversation_id and reuse it for subsequent loads to maintain continuity reference.
• Make sure both sys.user_id and conversation_id match exactly as generated by Dify. Any mismatch, or mixing conversations created via API and UI/iframe, will prevent history from loading reference.
• Dify uses localStorage keyed by appId and userId for session persistence. If you switch users or devices, ensure you use the same sys.user_id and conversation_id, and consider clearing localStorage if you encounter issues reference.
• There have been bugs in some Dify versions where passing these parameters did not work as expected. If you’re not on the latest version, upgrading is recommended reference.

In summary: use sys.user_id and conversation_id (not sys.conversation_id), ensure both are encoded and match Dify’s records, and avoid mixing API/UI-created conversations for the same user. This should enable chat history to persist across devices.

To reply, just mention @dosu.

---

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

   

[dapicester]

@dosu on the first bullet item you say:

Pass the user ID as the sys.user_id parameter (GZIP-compressed, Base64-encoded, and URI-encoded), and the conversation ID as conversation_id (not sys.conversation_id) in the iframe URL. For example: ...?sys.user_id=ENCODED_USER_ID&conversation_id=UUID #27684 (reply in thread).

But in the summary you say:

ensure both are encoded and match Dify's records

Do you mean I need to gzip + base64 encode + uri encode only the user_id and pass conversation_id as it is? Or should both encoded?

[dosubot[bot]]

You should declare user_id (not sys.user_id) in your "User Input" node. When you pass sys.user_id in the iframe URL, Dify automatically maps it to user_id in the workflow context, so you'll access it as user_id inside your flow. No need to declare or reference sys.user_id in the workflow itself—just use user_id.

To reply, just mention @dosu.

---

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

   

[dapicester]

It does not work.

[dapicester]

@dosu I do as you suggest: pass my user ID encoded as sys.user_id and conversation_id as plain UUID. If I open on another browser then it starts a new conversation. I discovered that this happens because the localStorage has no conversationIdInfo value. If I use the browser developer tools to set the conversationIdInfo to the value {"[conversation_id]": {"[user_id]": "[conversation_id]"}} then the browser does load the previous conversation. Is there anything I need to do programmatically?

[dosubot[bot]]

This is a known limitation of how Dify handles conversation persistence in iframes: conversation history is tied to a browser’s localStorage under the key conversationIdInfo, which is not synced across browsers or devices. Passing sys.user_id and conversation_id in the iframe URL is necessary, but Dify’s frontend still relies on finding the correct mapping in localStorage to load the history. There’s no built-in or documented way to programmatically sync or pre-populate conversationIdInfo across devices—restoring history on a new browser requires manually setting that localStorage entry before the iframe loads, just as you did with the dev tools. If cross-device persistence is critical, you’d need to implement your own script to sync this mapping (for example, via your backend and a small client-side script) before loading the iframe. See discussion and code reference for details.

To reply, just mention @dosu.

---

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

   

[dapicester]

@dosu is there a postMessage() I can send or can I listen to window.addEventListener('message', ...)?

[dosubot[bot]]

Dify’s iframe does not support sending commands or syncing conversation/user info via postMessage, nor does it emit postMessage events you can listen for in the parent window. Conversation state is managed entirely in the iframe’s localStorage, which is not synced across browsers or devices. There’s no built-in API for programmatically syncing or resetting conversation state using postMessage or similar methods—workarounds involve manually syncing localStorage or reloading the iframe with the correct parameters, but these require custom scripting outside of Dify’s current features citation citation.

To reply, just mention @dosu.

---

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

   

[dapicester]

@dosu can you help me ping any mantainer? I would like a human to have a look at this issue.

[dosubot[bot]]

I can't directly ping or assign human maintainers, but your issue is well-documented here and visible to the Dify team. You've followed all recommended steps for cross-device conversation persistence in the iframe, but it appears to be a limitation or bug in Dify's current implementation—conversation history relies on localStorage and isn't synced across devices, and there’s no supported way to programmatically sync or trigger this via postMessage or other APIs.

This thread now clearly summarizes the technical details and the need for maintainer review or a possible feature enhancement. Maintainers and contributors monitoring this repository can see your request for human attention. If a maintainer is available, they can step in to provide further guidance or escalate the issue.

To reply, just mention @dosu.

---

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

   

[dapicester]

Can a human have a look at this issue?

[dapicester]

I wounder if it could be possible to use the postMessage() API to send Dify's iframe en the existing sys.user_id and conversation_id? On Dify's side it should then set the conversationIdInfo key on localStorage with the properly formatted data.

[arcaela]

If you need persistent conversation history for embedded chatbots, Arko Studio has it built in -- each chat session is stored and the agent has cross-session user memory. You can access everything via the REST API or embed it however you need. Free tier available with API keys, OpenAI-compatible format.

[dapicester]

This looks like an ad. Is this related in any way to Dify? Can this help with my issue without moving to a different service/provider?

[dapicester]

I had to give up on the iframe integration. I used the API to implement the chat interface in my application.