Adding ESS Chat Capability to a Standard Homepage

If you’re reading this you’ve probably already seen the chat capability that ServiceNow provides. This is a great feature but it’s only currently available if you deploy the ServiceNow content management system (CMS) along with it. I recently worked with a co-worker, Greg Willis, to develop a way to add end-user Help Desk chat capability to a standard homepage. This article explains how you can do it too!

The basic concept behind this is to leverage a CMS site page with a chat link inside of the standard frameset on a homepage. This is accomplished by setting up the CMS site, page and content, and then putting that page inside of an iframe widget on a homepage. Here are the step-by-step instructions.

1) Install the Content Management and Chat Plugins

This solution doesn’t change the fact that end-user chat capability is only supported by the CMS plugin. You don’t have to set up a full-fledged CMS site, but you will need to install the plugin. Here’s the CMS wiki link for more information. You’ll also need to make sure you have the chat plugin installed.

2) Set up a new ‘Site’ record

This tutorial assumes that you don’t want to use a full CMS implementation. In order to get the chat functionality we need, you can set up a basic CMS site with a single page. Navigate to ‘Content Management->Sites’ and create a new site record. You only need to fill in the following information…
Name: Standalone Chat
Suffix: chat

IMPORTANT!!! You’ll need to come back to your site record after completing step 3 below to fill in the ‘Home page’ value for your site!

3) Create a new page for your chat site

The page is what will actually display the chat widget. The important thing here is to choose a layout that will look good in the widget we’ll create later and to make sure to associate the page to the site you created in step 2. Here are the page settings you should use based on the input from step 2 above.
Name: Chat page
URL suffix: chat
Layout: CMS 1 Column
Content site: Standalone Chat

IMPORTANT!!! Once you’ve created this page you should go back to the site record created in step 2 and set this page as the ‘Home page’ value in your site record!

4) Add a new Dynamic Content block to your page

From your new page, click the ‘Edit Page’ link at the bottom of the form. Once in the edit view, click the ‘Add content’ link and add a New Dynamic Content block as shown here…

Your Dynamic Content block should be configured with the following settings…

‘Chat’ Dynamic Content block

The code here is set up to use the out-of-box chat queue for end users. If you need to change this to a different chat queue, you’ll need to replace the sys_id in line 3 below with the sys_id of your chat queue.

Name: Chat
Dynamic content:

<div style="padding-top: 100px;">
<div class="live_workqueue_button cms_menu_vertical_blocks_container" style="margin: 0; padding: 1px 4px;">
<td style="vertical-align: middle;"></td>
<td class="cms_menu_vertical_blocks_title" style="vertical-align: middle; white-space: nowrap;">
<h2>Help Desk Chat</h2>

If you’re running an instance with pre-October 2011 release code, you may receive an error when clicking your chat button. If so, you’ll need to change the ‘onclick’ portion of the script above to look like this instead…, 'c54f0abf0a0a0b452db84664f409c79c', 'Help Desk Chat'); return false;

This changes with the October 2011 release so you’ll need to change to the syntax in the code block above when upgrading to October 2011 or later. See this wiki article for more details.

5) Create a UI page with an iframe for your chat page

This is really the key to the entire solution. As I’ve explained above, the ESS chat queue only works in the CMS setup. That’s why we’ve gone through all of the trouble of steps 1-4 :). Now we just need to put our CMS page in an iframe so that we can view it on a regular homepage. You can do this with a simple UI page created by navigating to ‘System UI->UI pages’, but if you want it to work in a homepage widget this step needs to be followed exactly.

‘render_gadget_standalonechat’ UI page
Name: render_gadget_standalonechat

<iframe id="chatframe" style="height: 320px; width: 100%;" src="chat" frameborder="0" scrolling="no"></iframe>

There are 3 important parts of this UI page. The first is the name. Because we want this to be included as a homepage widget, we need to name our UI page starting with ‘render_gadget_’. Second is the ‘src’ value from the iframe tag. This points to the suffix name of the CMS site set up in step 2 above. The third important piece is the height of the iframe. You can adjust this to meet your specific needs, but I’ve found that it should be no less than 320 pixels if you want it to look right.

6) Create or modify a Widget record

This step is only necessary if you want to display the chat button on a homepage. I’ve explained how to set up a widget and a UI page like this before so I’ll link to that solution for the instructions. Just follow the part about the widget, not the UI page there.

7) Add the widget to a homepage

Once you’ve set up your UI page and Widget record correctly you can open up a homepage and click the ‘Add content’ link in the top-left corner of the page. You’ll see your widget category name followed by the name of your widget in the second box to add to a homepage.

If you’ve followed the steps above correctly, you should have a working chat link on your homepage that looks like this…

Because the entire chat functionality is part of a dynamic content block, you can change the look of the button any way you like by modifying that HTML. Here’s a quick example I came up with to change the icon and the text a bit.

Want more? This same idea can be applied to the Live Feed to bring ServiceNow Live Feed functionality to user homepages. Click here to see how!

Date Posted:

September 15, 2011

Share This:


  1. Jim Coyne September 15, 2011 at 10:13 am

    That’s cool guys, thanks.

  2. Abhijat Shrotriya September 15, 2011 at 12:31 pm

    Thanks Mark, This is really helpful!

  3. Russell Gabriel September 15, 2011 at 12:44 pm

    Very helpful, thank you.

  4. Donte Hooker September 15, 2011 at 5:17 pm

    This is great

  5. Russell Gabriel September 20, 2011 at 11:12 am

    I’m having trouble with the UI Page properly displaying the Chat link. I’ve got the content management site and page working and can test the link there ok. I’ve also created the UI Page and the Widget, which are available to be added to the homepage. When I add the widget though, I get an iFrame with the entire homepage in the frame, not the chat link. I think the problem is in the UI Page, but I can’t determine how to correct it yet. I have the UI page exactly as you have it in the article.

    Any ideas as to why I’m getting the iFrame with the homepage inside it?

    • Russell Gabriel September 21, 2011 at 2:00 pm

      I have been able to get it to work. Initially I got it to display properly by modifying the UI Page’s source string to the full path to the page (src=”[https://ip address:port/]Chat/”). I then narrowed it down to just the relative path (src=”Chat/”). I also believe the name is case sensitive here.

  6. Alex Brandsma September 29, 2011 at 1:10 pm

    Great! Now something like this for the Live Feed!?

  7. Chris King October 15, 2011 at 11:52 am


  8. Andrew Yoward November 15, 2011 at 5:44 am

    Is there a way that you can get the chat window to open automatically when you log in? Currently, with my service desk staff, they don’t tend to use chat and I would like to encourage wider use as I’m pushing use of the ESS portal. If no one navigates to Social IT and opens Chat, no one will know when there is an end user on there trying to get help. It would be easier to automate it on log in I wager than to try and get people into the habit of once they log in, navigate to the Social IT menu item and click on Chat.

    • Mark Stanger November 15, 2011 at 9:58 am

      That’s possible but it’s kind of a tough thing to manage in the UI. I’m guessing that you would probably get lots of pushback from IT users. Ideally, you would manage this type of situation through policy. If you’re going to allow users to use chat, you need to have a policy (and enforce it) that someone from support is managing the chat queue at all times that a user could be asking questions.

  9. Matt Wascak December 13, 2011 at 11:16 am

    I follow this all the way up to the widget. In the end what does you chat widget look-like?

    • Mark Stanger December 13, 2011 at 11:23 am

      Check out the ‘Custom Widgets’ in the post I link to above. You should just have to change this line to match the name of your widget and the UI page you create.

      ‘Knowledge Search’ : { ‘type’ : ‘kbsearch’ }

  10. Russell Gabriel December 13, 2011 at 12:12 pm

    Mark, do you know of a way to add the “Help the Helpdesk” link to the banner section of the SN page instead of within an iframe on the homepage? The only problem I have is the real estate used by the iFrame on the homepage…for us, it would be better if we could make it always available via the banner much like the ESS portal page is made. This way, the chat session opens in a separate window as well.

    • Mark Stanger December 13, 2011 at 2:12 pm

      I’ve never seen that done. I think the quickest solution to preserve the real estate within the frameset would be to just use a module and have the module open in a new window. You should be able to set a target value of ‘_blank’ in the module definition to pop up the page in a new window.

  11. Adam February 17, 2012 at 7:42 am

    Mark – great document !!! Thank You

    Question – would it be possible to also include the “” window on the homepage? This would be perfect to have embedded on this page, so support would see when requests are coming in

    • Mark Stanger February 17, 2012 at 9:05 am

      You can put anything in an iFrame widget for a homepage in the same way I’ve done this one. The trick is usually to get the size right. iFrames don’t really do variable height very well and it’s hard to make things look right in an iFrame sometimes. Give it a try and let me know!

  12. Gustavo March 7, 2012 at 12:53 pm

    Awesome!! but Mark, do you think it’s possible to add the same link on the “Application Navigator”? on any module?

    • Mark Stanger March 7, 2012 at 12:56 pm

      Yes. All you have to do is set up a module and point to your cms page URL…just like you do in the UI page here. Just point a module to the CMS page.

      • Gustavo March 8, 2012 at 8:35 am

        A couple of questions:
        Do you have a guidance about how to point my module?, I mean an URL example?
        What about the chat window? where it loads? do I need to define a new layout where the chat window is going to load?
        I apologize for my lack of knowledge, but I’m still a newbie, please be bear with me :)

        • Gustavo March 8, 2012 at 10:06 am

          I’m using this parameters

          Link type: (URL from arguments)

          But loads the original chat window, not the ESS chat window, and that’s what I’m looking for, so I don’t know what do I need :S

          • Mark Stanger March 8, 2012 at 12:55 pm

            In step 2 above you create a CMS site with a suffix of ‘chat’. In step 3 above you create a content page with a URL suffix of ‘chat’. All you have to do is set up a module to point to that cms URL (which is a combination of the site suffix and page suffix). Using the example I’ve created here, your module arguments would need to point to this url…


            If your cms site and page have different suffixes then you need to adjust accordingly.

  13. Gustavo March 8, 2012 at 1:13 pm

    Thanks Mark! finally works!!! :) I really appreciate your support.

  14. Stig Brandt May 16, 2012 at 3:27 am


    I’m completely new to service-platform, but this was working right away both the livefeed and chat guides.

    I’m just wondering how you as the ITIL User – can get the chat widget on his homepage and then see the different chat queues/groups:

    – end user incident chat
    – it incident group chat


    Thanks in advance

  15. brumiou November 20, 2012 at 8:02 am

    thanks a lot for this solution.
    I tried it, and it works if I go to the page record and click on View Page.
    But if I add the block to a homepage and click on the chat, I can see in the javascript console this error : Uncaught ReferenceError: LiveEvents is not defined
    Do you know where it can come from?

    Thanks a lot



  16. Dhanraj December 13, 2012 at 3:33 am

    I tried all the step that you mentioned. When I hit the “Help Desk Chat” link on my homepage it doesnt not load the Helpdesk chat screen. I see the this error on the javascript console screen “Uncaught ReferenceError: LiveEvents is not defined”

    Please note that I have replaced the sys_id of the chat queue and the chat queue name in the ui frame code.
    Instance is on Berlin release and a MSP environment.

    • Mark Stanger December 13, 2012 at 5:44 am

      The only thing I can suggest is that you follow the instructions again exactly, and make sure that all of your code is going into the global domain. I’ve validated that this works correctly on Berlin in a domain-separated environment.

      • Dhanraj December 13, 2012 at 10:45 pm

        Thanks Mark !! I got it working by building an widget to launch the Helpdesk chat screen from the homepage.

        I appreciate your help each time I reached out to Service-now Guru. Couple of years back you advised to set our MSP instance to “Deny All” policy to close out the security vulnerability of “Allow All” model. It was an cumbersome exercise considering we had 3 customers live on the platform at that time for couple of years. However we were able to make it through and helped make the platform secure.

        Dhanraj Poojari

        • Mark Stanger December 14, 2012 at 4:43 am

          Awesome. Thanks for the comment and I’m glad you got things working correctly.

  17. Gil Brucken December 19, 2012 at 11:38 am

    Hi Mark,

    This has been very helpful. I am trying to set up a “Help Desk Chat” link on my ESS homepage. Everything seems good until I try to add the built widget to the page. It shows “Form not found” instead of the link. I have verified that the link works on the Content Management/Pages section and also in the UI Page. While I’m not a Javascript expert, I did follow your linked article and made changes to the “Sections” section as you described, but copied and pasted in the Javascript otherwise. Any idea as to what I might be missing? I appreciate any assistance that you may be able to provide. Thanks!

    • Gil Brucken December 19, 2012 at 12:53 pm

      Hi Mark,

      Never mind. I had a space in front of “render_…” as the name of the UI page. I’m good! This is awesome. Thanks for sharing!


  18. Faizeal March 13, 2013 at 2:00 am


    Thanks for sharing this details. Its working good and another one thing i just want to know. How to Create an incident from chat?

    Could you please help on this?



    • Mark Stanger March 13, 2013 at 6:45 am

      You can do that with chat actions. There’s actually a chat action set up by default for creating incidents. Check out this wiki article for details. Any follow-up questions should probably be asked on the ServiceNow forums.

      • Faizeal March 13, 2013 at 8:20 am

        Hi Mark,

        Thanks for your reply, I can create an incident from chat. Another one thing, I set up the above steps, Chat window is available only inside the frame i cannot move that.How do we change like that?

        • Mark Stanger March 13, 2013 at 8:48 am

          The only way to set this up is to present it inside of a frame. You can increase the size of the iframe by modifying the code from step 5 above, but that’s all you can do.

          • Faizeal March 13, 2013 at 9:14 am

            Thanks. Suddenly i cannot close close the chat window it goes to frame left corner.i cannot drag that chat window. It has showing half of the chat window What i have to do now?

  19. Mark Stanger March 13, 2013 at 9:43 am

    @Faizeal. You need to make the iframe big enough so that you can close the window. That’s why it was set to the size I set it to.

  20. Eric May 30, 2013 at 2:57 pm

    Mark, Anyway to make this available so this can be given only to some ESS users . like by group membership or location

    • Mark Stanger May 30, 2013 at 4:50 pm

      Hey Eric, there are ways to limit the access to the widget by modifying the widget record itself, but it becomes problematic for ESS users because they all share the same homepage. I think the best you could do would be to modify the HTML to alert with a message instead of popping open the dialog if the user wasn’t in the correct group. It’s not a simple fix though and I don’t have anything pre-built for it.

  21. Ian June 10, 2013 at 7:43 am

    Thanks for this. We’re on an older instance (running Berlin) and don’t have the self-service portal set up. The ability to add this in to the home page means we can use the chat queues but don’t have to implement a full custom portal just yet. I do have one query. On setting up the chat from my admin account, everything works fine. However, when tested from an ITIL or self-service user account the chat window opens but doesn’t always add the user to the chat queue. I have to close the chat windows and refresh the home page frame in order to get it to work. There don’t seem to be any errors coming out in Firebug. Any ideas where I should look to resolve the problem? I’m running out of places to look. Would it be a permissions thing on the Chat Queue Entry table?

  22. Kris K July 22, 2013 at 7:23 am

    Great post. Is there a way to add the help desk chat feature to a wizard or a catalog item so users are able to get help?

  23. Ethan October 16, 2013 at 7:17 am

    Could you possibly detail the process for changing the icon that is used for chat? I see the section but I don’t know where to find that image (if that’s the reference to the image) or how to replace that section with an image of my own.

    Thank you for this post!

    • Mark Stanger October 16, 2013 at 7:30 am

      You can upload your custom images using the ‘System UI -> Images’ module. Then, tust replace the following line with one of your own…

      <span class="i32 i32_support"></span>

      Something like this for the new line should get you started.

      <img style="height:50px" src="/helpdeskChat.pngx">
  24. Ethan October 16, 2013 at 10:05 am

    Fantastic! Thank you for the quick response.

    Follow up: This works perfectly for my standalone page and widget. This may be an entirely different topic (?) but how can we use this icon in place of the stock one on the header of the ESS page? The options for directly editing the HTML there seem limited and I can’t seem to find a macro for it.

    • Mark Stanger October 16, 2013 at 10:13 am

      ServiceNow has done a pretty good job of burying that for no apparent reason. You should be able to override the image by uploading a new image of your own (32X32 size works best). The important thing is to give your image an identical name to the out-of-box image so that it overrides it. Naming your new image ‘images/sprites/i32.png’ should accomplish this. You’ll need to hit the ‘’ URL to flush your database cache after making this change. Check out this article for details on this technique.

  25. Matt B April 11, 2014 at 10:34 am

    Has anyone tried to do this same sort of thing but with a public chat room?

  26. Brandon Williams April 18, 2014 at 3:32 pm

    Thank you for the tip. It was very helpful. I have ESS configured and my users are able to initiate a chat session from their ESS homepage. I’m working on a solution for Service Desk Staff. I’m trying to insert the Service Desk Chat window from on the homepage. This way when the Service Desk staff opens their homepage they will see Users Waiting in the Service Desk Chat queue. They can simply click the button to Answer Next User right from their homepage. Anyone know how to do this?

  27. NanD December 15, 2015 at 6:48 am

    Hello Mark,

    I have tried all these steps. But when I click on the ‘Help Desk Chat’ link on my homepage, it is not taking me to the chat box. It does nothing. It stays undisturbed.
    Our instance is MSP and recently upgraded to FUJI. Please provide some light on this issue.


    • Mark Stanger December 15, 2015 at 7:04 am

      Not sure what the issue might be in your instance. I do know that this works in Fuji and I’ve tested it successfully there.

  28. Ravi April 28, 2016 at 1:22 am

    Hi Mark,

    Is it possible to initiate a chat window just by clicking on a custom module under self service application, instead of navigating users to the cms page and then clicking on help desk chat link?

    • Mark Stanger April 28, 2016 at 5:13 am

      Not with the way ServiceNow has created the chat capability currently.

  29. Diego Cañete July 11, 2017 at 9:22 am

    Hi Mark,
    Is possible permit see change details to user wiouth itil roll? meaning end user
    example: Activity,Details or how is working on.
    Beacuse, some users (key user) losting the trasability on her request.

    • Jim Pisello July 14, 2017 at 10:13 am

      Hi Diego,

      Yes, you can allow users without specific roles such as itil to read fields on tables. You would need to modify some ACL records, or possibly create some new ones, depending on your specific needs. If you’re not familiar with working with ACLs, you can start with this article:
      Access Control Rules

Comments are closed.




Fresh Content
Direct to Your Inbox

Just add your email and hit subscribe to stay informed.