Embedding a Dify Chatbot in Your Website

Who this is for

This guide is for readers who have already published a Dify web app and want to put it on their own website. By the end you will know which embedding method fits, how to set up the chat bubble or the iframe, and where to look first when something goes wrong.

Embedding is the same app

Embedding is not a separate way to publish. After you publish an app, Dify gives you a web app URL. The embedded version is the same app, shown inside your page instead of as a standalone page^[1]. Changes to the app's configuration apply automatically to every embedded location^[1].

Dify offers four ways to present a web app: a chat bubble component, an iframe, JavaScript control for custom styling and behavior, and a responsive design that adapts to different display forms^[1]. In practice, the first two are the ones most sites use.

Step 1: get the embed token

Open your app's Access Entry tab. On the Web App card, click Embed on website to find the unique token for the app^[1].

Set up the chat bubble

The chat bubble shows the web app as a floating button. When a visitor clicks it, the app opens as an overlay, so the visitor never has to leave the page^[1].

The configuration lives in a difyChatbotConfig object on window. The token field is required and holds the app token from Dify^[1]:

window.difyChatbotConfig = {
    // 必需：来自 Dify 的应用令牌
    token: 'YOUR_TOKEN',

That is the opening of the object; the full configuration also includes optional settings. The baseUrl is set automatically based on isDev, and the example uses https://udify.app. The draggable option controls whether visitors can drag the button, and dragAxis accepts 'x', 'y' or 'both'^[1].

containerProps sets the bubble's position and style, and className attaches a custom CSS class. The example places the button 20px from the right and 20px from the bottom^[1]:

    containerProps: {
        style: {
            right: '20px',
            bottom: '20px'
        },
        className: 'custom-chat-button'
    },

inputs pre-fills user context. Its keys must be variable names from your Dify app, and the example passes name and department^[1]:

    inputs: {
        name: "John Doe",          // 来自你的 Dify 应用的变量名
        department: "Support"
    },

systemVariables carries system variables used for tracking, such as user_id and conversation_id. userVariables carries user profile information, such as avatar_url and name^[1].

The four input types are handled differently. text-input and paragraph accept any value, and strings longer than the maximum length are truncated. number accepts a number or a numeric string, and a string is converted with the Number function. options accepts any value, but it must match one of the options configured in the app^[1].

When the embed.js script creates an iframe, each input value is compressed with GZIP, base64-encoded, and then appended to the URL^[1].

Embed an iframe

An iframe places the web app directly in the page content, so visitors see it without clicking a button first. Set src to https://udify.app/chatbot/ followed by your app token, replacing YOUR_APP_TOKEN^[1]:

<iframe
  src="https://udify.app/chatbot/YOUR_APP_TOKEN"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

The iframe is always visible, supports the app's full feature set, and looks like native page content rather than an overlay. It needs only HTML, with no JavaScript configuration^[1].

Which method to choose

• Customer support apps: the chat bubble fits best, because it stays out of the way until visitors need help^[1].
• Forms and workflow apps: when the app is the main content of the page, use an iframe^[1].
• Product demos: on a landing page, an iframe lets visitors try the AI features immediately^[1].
• Multi-page sites: when every page needs the same app, use the chat bubble, since one snippet covers all pages^[1].

Customize the bubble

The chat bubble button can be restyled with CSS variables. --dify-chatbot-bubble-button-bg-color sets the background color and defaults to #155EEF. The width and height variables default to 50px, and the border radius variable defaults to 25px^[1]. The distance from the bottom and right edges is set by --dify-chatbot-bubble-button-bottom and --dify-chatbot-bubble-button-right, both defaulting to 1rem. The hover effect is set by --dify-chatbot-bubble-button-hover-transform, which defaults to scale(1.1)^[1].

To change the background color to #ABCDEF, add this CSS^[1]:

#dify-chatbot-bubble-button {
    --dify-chatbot-bubble-button-bg-color: #ABCDEF;
}

Troubleshooting

If the bubble does not appear, check that the token matches the one shown under Embed on website on the Access Entry tab, that the configuration loads before the embed script, and that the browser console shows no JavaScript errors^[1].

If an iframe does not load, confirm that the URL contains the correct token, check that your site's Content Security Policy allows iframe content, and make sure both your site and the Dify app use HTTPS^[1].

If your configuration change does not show up, publish the web app again. An app must be published before it can be embedded, and the changes reach the embedded version only after republishing^[1].

Where to go next

For the full list of CSS variables and input types, read the "Embed Web App" page in Dify's documentation^[1].

Adapted from Dify's documentation page on embedding web apps in websites^[1], released under the CC BY 4.0 license.