[OpenAI-compatible + Custom Citations] How can I make “Referenced snippets” open my own URL instead of Dify Knowledge?

[dylan-labs]

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

Post

Hi all — I’m integrating my own backend via OpenAI-API-compatible in Dify.
The tag works great (it auto-folds as “Reasoning” without any extra logic on my side).
Now I need citation links to open my own endpoint (e.g., https://my.domain/kb/open?doc_id=...) instead of the built-in Dify Knowledge page.

Environment

Deployment: Self-hosted / Cloud (please specify)

Dify version: vX.Y.Z (please fill in)

App type: Workflow (with retrieval)

Model provider: OpenAI-API-compatible (pointing to my custom HTTP endpoint)

Goal

When the user clicks a referenced snippet / source, it should open my custom URL rather than Dify’s internal knowledge page.

Current Behavior

Dify shows the “References / Sources” area under the answer (coming from retrieval).

Clicking a reference opens Dify’s document page.

I also stream my own references as JSON inside content, but the UI doesn’t auto-render them as links.

What I currently output

1. Last SSE chunk (from my model, simplified)
   { "event": "message", "id": "daf07733-9f4d-4dfe-b083-d464c1a23d0c", "answer": "<final>...answer text...</final>\n<doc_references>\n[{\"doc_id\":\"0049707d4d284233a97bbeacccc2d29b\",\"doc_name\":\"...Policy v1.pdf\"},{\"doc_id\":\"bf92788fe0af49aebbc26d0d61ff1616\",\"doc_name\":\"...Notice.pdf\"}]\n</doc_references>" }
2. message_end event metadata (excerpt)
   { "event": "message_end", "metadata": { "retriever_resources": [ { "dataset_id": "b5ab57c7-...", "document_id": "0049707d4d284233a97bbeacccc2d29b", "document_name": "...Policy v1.pdf", "score": 0.71, "doc_metadata": { "page_index": 0, "chunk_index": 51, "file_name": "...Policy v1.pdf" } } ] } }
   Attempts so far

Embed <doc_references>[...]</doc_references> in content: shows as plain text; not clickable.

Render Markdown links inside (e.g., Title): works, but it’s a separate list from Dify’s built-in “References” block.

Workflow code node that parses <doc_references> JSON and appends my own Markdown links to the answer: also works, but still parallel to the built-in references.

Couldn’t find a setting to override the built-in reference link target.

Questions

Is there an official way or config to have the built-in “Referenced snippets / Jump to knowledge” use a custom external URL (e.g., read metadata.external_url or doc_metadata.url first, and fall back to the default)?

With External Knowledge API, can we return records[].metadata.url and have the UI open that URL directly? If yes, which field name is honored by the UI?

If front-end tweaks are required, where is the component/logic that builds the “open knowledge” link for references? Any recommended hook/extension point?

Is there a way to hide the built-in reference block so I only show my own rendered links (from the workflow), avoiding double displays?

Notes

requires no special handling on my side; Dify folds it automatically as “Reasoning.”

Ideal outcome: keep Dify’s reference cards but override their click URL to my endpoint, or expose a documented config/hook to do so.

Thanks in advance for any guidance or examples!

[dosubot[bot]]

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

There isn't an official config or API field to override the built-in "Referenced snippets" link target in Dify. The front-end always builds the reference link as an internal URL using dataset_id and document_id, and does not check for custom fields like metadata.url or external_url in the citation data. The relevant logic lives in the Popup and Citation components (popup.tsx, index.tsx), and the CitationItem type does not include a URL field. There are also no hooks, props, or extension points to customize the link or hide the reference block via config or API response—you'd need to patch the front-end to support this behavior citation.

To implement custom reference URLs, you could extend the CitationItem type to include a url or external_url field, update the rendering logic in the Popup component to use it if present, and adjust your backend to provide this field. Hiding the built-in reference block would also require a code change, such as conditionally rendering the Citation component in the Answer component (answer/index.tsx). There is no evidence that the External Knowledge API supports a metadata field for this purpose citation.

To reply, just mention @dosu.

---

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