Using Web Widget to embed customer service in your website Follow

all plans

The Web Widget enables you to embed Zendesk Support features in your website or Help Center so your customers can get help without leaving your website or Help Center. Your customers can get quick access to:

  • Search for knowledge base articles
  • Live chat with an agent
  • Contact form to submit a ticket

The widget appears in the bottom corner of your website or Help Center. You configure the components you want in the widget, then add the widget code your website or Help Center.

You must be an administrator to set up and manage Web Widget.

Note: You can now use the Web Widget with a restricted Help Center content. For more information, see Using restricted Help Center content with the Web Widget.

About browsers supported by Web Widget

The Web Widget is supported on the following browsers as of January 23rd, 2017.

On desktop:

  • Google Chrome: latest two versions
  • Microsoft Internet Explorer: latest two versions
    Note: Keep in mind that Internet Explorer 11 is susceptible to memory leaks, which may impact performance.
  • Mozilla Firefox: latest two versions
  • Apple Safari: latest version

On mobile:

  • iOS Safari: latest two versions
  • Android browser: latest version
  • Chrome Mobile for Android and iOS: latest version

Configuring the components in your widget

You can configure your widget to include the following components:
  • Help Center search for knowledge base articles
  • Zendesk Chat for live chat with an agent
  • Contact form for filing a ticket in Zendesk Support
  • Suggested articles based on the web page the user is on (contextual help)
Note: If you want to included restricted Help Center content in your widget results, you will need to configure other settings as well. See Using restricted Help Center content with the Web Widget for more information.
You can combine one or more of the components, as follows:
  • Contact form only
  • Zendesk Chat only
  • Contact form and Zendesk Chat
  • Contact form and Help Center
  • Contact form and Zendesk Chat and Help Center

When you enable multiple components, your customers are presented with the options at different times, not all at the same time. To understand how these options are presented to your customers, see Understanding the end-user experience.

You can choose whether you want the widget to appear on the left or right side of your site. If you're on Enterprise, you can remove the logo from the widget. Some advanced customizations are possible using the API (see Advanced customization of your Web Widget).

Adding the Web Widget also lets you better analyze your Help Center metrics (article views and searches), by allowing you to filter for only those coming from the Web Widget. For more information on working with Help Center analytics, see Analyzing Help Center search results (Professional and Enterprise)and Analyzing Help Center community and knowledge base activity (Professional and Enterprise).

To configure your widget

  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Customization tab.

    If this is your first time setting up the widget, click Get Started, then click the Customization tab.

  3. Enable the components you want in your widget:
    • Contact form: Click the toggle to Off if you do not want to allow customers to submit tickets in your widget.

      The contact form is enabled for your widget by default. Tickets submitted through the widget will contain the tag "web_widget."

    • Custom ticket fields: Click the dropdown menu, then select up to two custom ticket fields, if you'd like to include custom fields in your Web widget contact form.

      You can add a maximum of two custom ticket fields. Regular expression and Date custom fields are not supported. Ticket forms are not supported.

      Note: This option does not appear if you did not enable the contact form or if you do not have custom ticket fields that are visible and editable to end-users. Only custom fields that are visible and editable appear in the list. To make a custom field available for the widget, select For end-users: Visible and For end-users: Editable in the custom fields settings (see Adding a custom ticket field).
    • Chat: Click the toggle to On if you want to offer Zendesk Chat in your widget, when chat agents are online.

      This option is not available if you have not enabled Zendesk Chat. Click Set up Chat to enable Zendesk Chat now. 

      Tip: The Web Widget can be used in place of of the Zendesk Chat widget.
    • Help Center: Click the toggle to On if you want to offer Help Center search in your widget.

      This option is not available if you have not enabled Help Center for Zendesk Support. Click Set up Help Center to enable Help Center now.

    • Contextual Help: Click the toggle to On if you want to offer Contextual Help in your widget. Contextual Help suggests articles to the end-user that may be relevant to them, based on the page from which they accessed the widget.

      Note: To use Contextual Help, the Help Center option must be enabled.
  4. Beside Zendesk logo, click the toggle to Off if you do not want to show the Zendesk logo in your widget (Enterprise only).
  5. Beside Theme color, click the color picker to select a custom color for your widget.

    After you select your color, simply click away from the color picker.

  6. For Position: Use the drop-down menu to select either Right or Left.

    Your selection determines whether the widget appears on the bottom-right corner or the bottom-left corner of the page.

  7. Use the Web Widget button text: dropdown menu to select the text displayed on the Web Widget button.

  8. Use the Contact form button text dropdown menu to select the text displayed on the button that launches the contact form.

  9. Click Save changes.

    Now you are ready to copy your widget code from the Setup tab and add it to your website or Help Center.

Adding the widget to your website or Help Center

The Web Widget is fully optimized for the mobile experience and does not affect page load times. The widget is presented in the end user’s language, according to the language setting for end user’s web browser. You can force the widget to always appear in a specific language (see Displaying your widget in a different language).

You can add the Web Widget to any page of your website or to your Help Center. After you add the code, you manage changes in Zendesk Support, and with the Advanced Customization JavaScript APIs, and updates are reflected in the widget wherever it appears.

You cannot use SSO authentication in the Web Widget itself. However, you can restrict access by setting up SSO on your Help Center, or on the website hosting the widget. See Single sign-on options in Zendesk, and Using restricted Help Center content with the Web Widget.

Note: For advanced customization ideas using the API, see Advanced customization of your Web Widget.

To add the Web Widget to your website

  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Setup tab, if it is not already selected.
  3. Under the code box, click Copy to clipboard.

  4. Paste the Web Widget code snippet into your website's HTML code, before the closing HTML </HEAD> tag.

    You need to add the code to every web page where you want the widget to appear.

To add the Web Widget to your Help Center
  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Setup tab, if it is not already selected.
  3. Click the Add to Help Center toggle.

    This adds the Web Widget to your Help Center header code, and displays the widget on every page of your Help Center.

If you are on a Team, Professional, or Enterprise Zendesk Support plan, you can restrict the pages of your Help Center the Web Widget appears on via the Web Widget API, by modifying the zE.hide method. See Advanced Customization of your Web Widget and the Web Widget API documentation for more information.
Help Centers that are hostmapped and have restricted content may need to manually paste the snippet and update the subdomain to reflect the hostmapped domain, to have that restricted content enabled for the Web Widget.

Adding custom tags to Widget tickets from specific pages

All tickets submitted through the Web Widget include the URL for the page the user was on when the ticket was sent. Administrators can use triggers to add custom tags, agent assignments, and other actions to these tickets, based on the originating page, to streamline your ticket workflow.

For general information on triggers, see Triggers resources.

For example, let's say you are the administrator for a health care website, and you want to add the tag "peanut_allergies" to any tickets submitted through the Web Widget from a Help Center article about managing peanut allergies.

To add a custom tag to a ticket based on its originating page

  1. Click the Admin icon in the sidebar, and click Triggers.
  2. On the Triggers page, click Add trigger.
  3. Enter a descriptive title for your trigger.
  4. In the section Meet all of the following conditions: use the drop-down menus to select the following options:
    • Ticket: Channel
    • Is
    • Web Widget

      Click the [plus] and add another condition with the following options:

    • Ticket: Comment text...
    • Contains the following string
    • In the text entry box: Enter the URL of the page you want to trigger the custom tag.
  5. In the section Perform these actions: select the following options:
    • In the drop-down menu: Ticket: Add tags
    • In the text entry box: Enter the text of the tag you want applied to the ticket (for example, peanut_allergies).
  6. At the bottom of the page, click Create trigger.
With these conditions, any ticket that is submitted through the Web Widget, when the Web Widget is launched from the URL included in step 4 above, has the tag “peanut_allergies” applied to it upon submission.

Understanding the end-user experience

In your widget, you can enable components to combine knowledge base search, live chat, and contact form.

Only one option is presented to the end-user at a time. The order of options that appear in your widget depends on which options you have enabled for your widget and, for Chat, whether agents online.
  1. Knowledge base search. Customers are presented with Help Center knowledge base search first, for ticket deflection, if Help Center is enabled for your widget. Customers can enter a search term, and if matching results are found, the top three appear. If more than three matching results are found, a "View more" button allows users to expand the article list to display up to nine articles. The end-user can click an article from the results, and it will open in the widget.

    Note: You can remove the "View more" button from the widget by modifying the API. See Hiding the "View more" button for information.
    If you have Contextual Help enabled, up to three suggested articles appear below the search box. The suggested articles are determined by the page from which the end-user accessed the widget.

  2. Live chat. Customers are presented with Zendesk Chat when:
    • Help Center is not enabled or has already been presented to the user and
    • Zendesk Chat is enabled and agents are online

    When Zendesk Chat is enabled for the widget and agents are online, end-users have the option to start a live chat.

    When end-users click Live Chat, they can fill in the information, then start chatting with an agent.

  3. Contact form. Customers are presented with a contact form to file a ticket when:
    • Help Center is not enabled or has already been presented to the user and
    • Zendesk Chat is not enabled or agents are not online and
    • Contact form is enabled

    When Zendesk Chat is not enabled for the widget or agents are not online, end-users have the option to leave a message, which creates a ticket.

    When end-users click Leave us a message, they fill in the information, add any useful attachments, then send the ticket.

    Note: You can disable the attachments feature by modifying the API. See Disabling ticket attachments for information.

Optimizing Help Center images for the widget

To make sure the images in your Help Center articles display correctly in the Web Widget, it’s important to make sure the images are added to the article at the desired size.

When Help Center articles are converted for viewing in the Web Widget, the article’s images are stripped of their attributes in the HTML tags (except for the src and alt attributes), and custom CSS rules are ignored. For most images, this isn’t a problem. However, if the original images are very big, and significantly resized in the HTML or in a custom CSS, they can appear awkwardly large.

Say, for example, you want to display an icon in your Help Center article. The icon’s original image is 300x300 pixels. In order to display it at a more reasonable size, the HTML is modified by adding the attributes width=“6%” height=“6%”.

In the Help Center article, the icon is 18x18 pixels, 6% of the actual image size. When the article is processed for the Web Widget, and the width and height attributes are removed, it balloons up to its original size and, even after being sized down to fit inside the widget, it’s too big for an icon.

Simply resizing the original image down to the size you want, rather than manipulating the size in your code, avoids this problem.

Streaming videos in the widget

If articles on your website or Help Center include instructional videos, your end-users can stream them right in the Web Widget.

To display correctly in the Web Widget, videos must be publicly available, and hosted on one of the following third-party services:

  • Vimeo
  • YouTube
  • Wistia

See Inserting videos into articles for more information.

If you have videos hosted by another service, we may be able to help. File a support ticket with your video hosting information and we'll work with our engineers to try to get things up and running.

Removing the widget from your website or Help Center

You can remove individual instances of your widget by deleting the code from the web page or Help Center. You can turn off all instances of the widget by disabling it in Zendesk Support.

To remove the widget from a web page
  • Delete the code from the web page.

To remove the widget from your Help Center

  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Setup tab.
  3. Click the Add to Help Center toggle to remove the widget.

To disable the widget and prevent it from appearing on your website and Help Center

  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Customization tab.
  3. Beside Contact form, Chat, and Help Center, click each toggle to Off.

    All three widget components must be turned off.

  4. Click Save changes.

    The widget will not appear on your website or Help Center.

Have more questions? Submit a request


  • 0

    @Kristi, currently there is no method to add a more button. This sounds like an interesting feature, and it would be great if you could add a feature request for it over in our Product Feedback Forum so the issue can gain more visibility.

  • 0

    Why the web widget could not appear in landscape orientation mode? Many tablet users browse web sites in this mode

  • 0

    @Arsenio I will create a support ticket for you

  • 0

    Is there any chance to rename the "Help" Widget? (e.g. Contact)

  • 0

    @Volunteer World - not currently, we'll bear it in mind for the future.

  • 0

    @Aaron, can you give an indication on if you guys are even considering the change that we can enable the Widget with only the helpcenter. For lots of reason we don’t always want to offer an email or chat option as other contact options are better suited to answering a customer question.

    For some reason it feels that Zendesk employs a "holier-than-thou" attitude with regards to how Brands should provide service when using your product.

  • 0

    Hi Stas,
    No plans for a 'Help Center only' version of the Web Widget at the moment.

    I'll share your feedback with the Help Center team as we do want customers to provide articles in-context if they might be of use to the end-user.

  • 1

    I am evaluating zendesk for our team. I notice that it says the web widget is only available to 'open zendesks'. Is there any work around for that with a closed zendesk? Or, any plans to make that available anytime soon?

  • 1

    Hi Aaron,

    My team is migrating back to Zendesk from UserVoice and I'm only now realizing that SSO is not supported with the widget. It's very important to us to know what accounts certain tickets are coming from. I saw a few other people were asking for it as well. Is there any plan to support this in the near future?

  • 0

    Is it possible to have the widget button placed in a fixed position?

  • 0

    Hi Johnd,

    There isn't a native way to fix the web widget to a particular position. I've not been able to find examples of this being done, but I suspect you could write JavaScript to relocate that component.

    If you were using the Zopim chat widget, there's a different API for that which does allow for this. If you figure out JavaScript way to do this, please post it here!

  • 0

    @Paul - there's no workaround for using the Web Widget with a closed Zendesk at present and we do not have any firm plans for it.

    @Joshua Unfortunately SSO is not currently available in the widget, we may look into it in the future. Although not ideal, as a workaround you could use the 'submitted from' URL that comes in at the bottom of all Web Widget tickets (if that helps identify the accounts that tickets have come from).

    @Johnd/Dwight - I do hear customers ask about positioning the widget more freely. It's something we're thinking about for the future.


  • 0

    Dear Zendesk-Team,

    I got a question. I am using some tables to illustrate things in my Help Center. Everything works fine. The problem is when you want to see that Help Center entry via Zendesk Widget it shows no table and just the text which is in the table. So It is not possible to read it.. I got about 30 rows and 3 columns. Am i doing it wrong or is this a know issue?

    Greeting Lukas

  • 0

    The Feedback tab has an option for entering a URL for company Privacy Policy. This is required for TRUSTe certification. Is there a comparable option for the widget?

  • 0

    Hi Rob, no, there isn't currently a comparable option in the widget at the moment - thanks for bringing it to my attention.

  • 0

    @Lukas, this is a known issue with some complex tables and rendering them in the Web Widget. We'll look into addressing this in the future.

  • 0

    First of all ...It would be a huge help if there is a way to search with in the 'Comments' of a page. I may not be raising this question/comment again.

    Have a question/comment about web widget's compatibility. Why would Zendesk not make the compatibility consistent across it's products? Zendesk and help center are compatible from IE 9 and above, while web widget is supported for only the latest two versions of IE!!! We are having serious difficulties explaining to our customers why some features does not work in a particular version of browser and while others does work.

  • 0

    Hi RA Admin,
    We do try to keep compatibility consistent where possible. With the Web Widget, we make use of a number of modern web technologies that are simply not supported by Internet Explorer 9 (hence the difference in browser compatibility).

    I appreciate that not all organizations have the freedom to run the latest versions of web browsers but as the technologies we use are generally supported by most other browsers, this was the direction we chose to go.

    On a related note, I believe Microsoft are dropping support for IE9 on all operating systems apart from Windows Vista and Server 2008 from January 12th, 2016 - see more info here:


  • 0

    I have noticed that the file the "Zendesk Widget script" loads the "" file twice on every request. (even on this page)
    Why is that needed? sounds like a lot of overhead to me
    Of course it will be cached, but why is it needed twice

  • 1

    Hi, Is there any way to hide/remove the link to the Help Center's original article within the articles in the widget?

    Edited by Marius Jacobsen
  • 0

    Hi Marius,

    We will be more than happy to provide guidance with the Web Widget, but unfortunately, we are unable to determine what you are trying to do. Would you be able to elaborate more on what you are trying to accomplish?

  • 0

    @Rutger, The double-tapped main.js and update.html are part of the release-based cache-refresh mechanism we use to ensure that visitors' browsers re-request a copy of main.js only when a newer version is available. If the browser is behaving correctly, you should also find that the second main.js request is fulfilled entirely from the browser's cache.

  • 0

    Can you specify what Help Center content is displayed per specific widget? For example, if I had a Section dedicated to a particular product type, could I make a widget for the web pages related to that product type, and have the Help Center search on those pages display only that section?

  • 0

    Those of you who want the ability to change the text of the widget from "Help" to something else (like "Feedback") should go vote for this feature request: Thanks!

  • 0

    Unfortunately, that's not a feature that we have right now.

  • 0

    If an account is using multibrand.

    Can a web widget be created for each brand to control which help center knowledge base content is searched?

  • 0

    @Paul, You can make one widget per brand.

  • 0

    @James Peterson, Do you know where I can find the instruction on how to create a unique widget for each of my brands?

    This article explains adding a widget to the default brand.

    I would like to enter the subdomain in the widget just like I can in the Feedback Tab.

  • 0

    @paul You can create a widget for your second brand by going to Admin--> Channels -->Widget and clicking Add Widget. You can then repeat for any other brands so that you could set up 1 widget per brand.

  • 0

    I had a stab at the Widget feature and unfortunately for our use case it just lacks too many features.

    To get an idea of the type of implementations we are using here is one - and here is another -

    To sum up the top features we miss:

    1. CSS customization - alot of people are asking for this

    2. running JS in the Widget. With the old feedback tab it was possible - pasting javascript code in the CSS customization window worked, I do realize this is a hack and officially unsupported

    3. the ability to have different widget instances. With the Feedback tab one could insert different instances to various pages, have submitted tickets tagged and treated differently in ZD (routed to different queues, etc)

    There might be a way to get this done with the Widget but that would imply adding a custom field named "Source", have that hidden from the user and pre filled using JS or have a query param passed in the Widget's iframe "src" (as we have done on )

    The Widget might be prettier (mobile friendly, better styled) but it lacks the flexibility and versatility of the Feedback tab.

    Hope this feedback helps,


    Edited by Mihai Tica

Please sign in to leave a comment.

Powered by Zendesk