How to embed Virtual Agent in an external site - Updated for Tokyo

[Victor Chen]

The ServiceNow Virtual Agent web client can be embedded in an external site other than your Portal. Below is a step-by-step guide on how to embed your Virtual Agent in an external site. It also contains steps on creating a custom URL, which is a required step. The official documentation can be found here. 

 

Example of Virtual Agent embedded on an external site. You can visit this site at http://victorchat.vwchen.com.  

Pre-requisites 

• Virtual Agent plug-in installed 
• A “paid” customer instance (a developer instance will not work in the long-term.) 
• Your own hosted domain, e.g. on GoDaddy. 

New in Tokyo

In the Tokyo release, we have created a Portable VA web client that can be directly embedded to any site via javascript. You can view the documentation here: Add the Portable Virtual Agent web client to a third-party website. 

1. You need to set up system properties per Step 2 below in the (Legacy) Process. 

• Set ‘com.glide.cs.embed.csp_frame_ancestors’ to: 'self' http://*.example.com 
• Set ‘com.glide.cs.embed.xframe_options’ to: sameorigin 

2. Configure CORS Rules for the REST API to give access across domains.

This rule gives the web domain you specify the rights to call the API that gives it access to the chat widget on the web page without a security restraint. All domains must share a common parent domain. Also, you must create a new CORS Rule for each subdomain that you want to support.

1. Navigate to All > System Web Services > REST > CORS Rules.
2. Click New.
3. On the form, fill in the fields.

   Field	Description
   Name	Unique name for the rule.
   Application	Scope of the application. Global is the default value.
   REST API	Name of the REST API. Select Conversation Consumer Account [now/cs].
   Domain	The domain for your website. For example: https://vwchen.com
   Max age	Default value = 0

4. On the HTTP Methods tab, select GET.
5. Click Submit.

3. Add this script reference to your external page header. Note: "site1.mycompany.com" is your instance URL, e.g. for me it's "victortokyo.service-now.com". 

<script src="https://site1.mycompany.com/scripts/now-requestor-chat-popover-app/now-requestor-chat-popover-app.min.js?sysparm_substitute=false"></script>

4. Create a ServiceNow chat instance on your external page within a <javascript> block.

const chat = new ServiceNowChat({instance: 'https://site1.mycompany.com'});

You can also configure the size, location, and color of your chat instance, for example:

Example with configuration

const chat = new ServiceNowChat({
	instance: 'https://site1.mycompany.com',
	context: {
		skip_load_history: 1
	},
	branding: {
		bgColor: '#333',
		primaryColor: '#000',
		hoverColor: '#EFEFEF',
		activeColor: '#AAA',
		openIcon: 'custom-open.svg',
		closeIcon: 'custom-close.svg',
		sizeMultiplier: 1.6
	},
	offsetX: 50,
	offsetY: 50,
	position: 'left',
	translations: {
		'Open dialog': 'Open chat',
		'Open Chat. {0} unread message(s)': 'Click to open',
		'Close chat.': 'Click to close',
	},
});

Final note: unless the user is logged in to ServiceNow, they can only use the embedded Virtual Agent as 'guest'. For authentication, view the documentation on how to trigger SSO.

(Legacy) Process 

For the steps, we will use http://example.com as the example host domain. In the screenshots, I use my live personal domain, http://vwchen.com.  

Note: This does not include steps for SSO authentication to use Virtual Agent as a logged in user. Users will only see topics with Role set to ‘Public’.  Article on SSO authentication on external site: Link. 

In your instance: 

1. Install the “Custom URL” plugin. 

2. Set the following system properties: 

Set ‘com.glide.cs.embed.csp_frame_ancestors’ to: 'self' http://*.example.com 

  

Set ‘com.glide.cs.embed.xframe_options’ to: sameorigin 

 

In your hosting service: 

3. Navigate to your hosting control panel (e.g. cPanel) and create a subdomain to eventually link to your ServiceNow instance. E.g. http://support.example.com. This subdomain does not have to be made public, it will redirect to Service Portal. Note: After creating, it may take several minutes for it to become active.  

 4. Navigate to your DNS manager to add a CNAME record to link your sub-domain to your instance. E.g. in GoDaddy, this is found in My Domains / Domain Settings / Manage DNS. For type, select “CNAME”. For host, enter the subdomain name, e.g. “support”, and for Points to, enter your ServiceNow instance. Once you click ‘Save’, it may take several hours (>6 hours) to propagate.  

 5. Create a website where you would like the chat client (widget) to appear on. This is the non-instance external site. In my example, I use another subdomain: ‘victorchat’, so http://victorchat.vwchen.com. Paste the code attached to this article to embed the Virtual Agent widget. It contains an HTML file to create a blank page with a green ‘Chat’ button. (The attachment format is .doc. Change to .html.)

Important: Within the code it will reference an instance URL “YOUR-INSTANCE-NAME-HERE". Update the instance link with your instance name.  

Return to your instance.  

6. With the “custom URL” plugin installed earlier, navigate in your instance to ‘Custom URL > Custom URLs’. Click “New”. In the “Domain Name” field, enter your created subdomain. In the “Service Portal” field, select Service Portal. Note: This will not work until after the CNAME is propagated.  

 

 7. When you visit http://support.example.com, you should now be taken to the Service Portal. Again, this may not be necessary for you, so you can hide this if your only concern is embedding the Virtual Agent.  

Embed Virtual Agent FAQs 

1. Do I have to use a custom domain? 

Yes, you must use a custom domain due to the increased scrutiny on 3rd party cookies and cross origin requests (CORS) from the major web browsers. This is a good thing as it increases overall security. For this to work you must put your ServiceNow site on a subdomain off the parent domain you want to embed the chat client on. For example, if you have the chat client embedded on https://mychatclientpage.example.com you must put your ServiceNow instance on a domain off example.com something like https://support.example.com. The page the client is served from should also be served over https. 

[Community Alums]

Thank you Victor for sharing! It's really helpful.

[Venla Pesonen]

Hi Victor! Thanks for the instructions. I noticed that the following message is printed to console when the chat window is opened in the page I'm developing, and also in your example page. Does someone know where this comes from and if something can be done about it?

AMB getClient() tried to access parent from an iFrame. Caught error: SecurityError: Blocked a frame with origin "https://victorchat.service-now.com" from accessing a cross-origin frame.

Thank you!

[Jacob Thesbjerg]

@Victor Chen I am in no way an expert on CORS, cookies, or any of that jazz, but I do have a question regarding the custom URL requirement. I have successfully implemented the VA in external sites without configuring a custom URL - with and without SSO - and I am just wondering how that's possible? I've used our xyz.service-now.com domain for the embed URL and set the two com.glide.cs.embed properties as described in the documentation and in this article.

[deepali123]

Hi Victor, 

                 we are trying to implement embedding virtual agent on external site but is there any external site which we can use free of cost through which we will be able to embed virtual agent.

[Victor Chen]

@Jacob9 - as of now it will work without a custom URL, since the third party cookie is passed between your site and your SN instance. Moving forward (Utah release timeframe), authentication will not work without custom URL. You'll need to specify and map a custom URL, otherwise you'll only be able to use VA on an external site as 'guest'. 

@deepali123 - not that I know of, I used a Wordpress site on a GoDaddy domain. 

[Manu4]

Hi @Victor Chen ,

I am getting this error, "AMB getClient() tried to access parent from an iFrame. Caught error: SecurityError: Blocked a frame with origin "https://instancename.service-now.com" from accessing a cross-origin frame".

in console

Because of this, not able to proceed with conversation 

Kindly help me on this.

Thanks,

Megha

[Diana27]

Hi Victor,

Can you clarify whether or not you have to install the Virtual Agent Plugin on your system to use the Portable Virtual Agent Web Client.

Thank you,

Diana

[Nicolas Labrada]

Do you still need to have custom URLs enabled after Tokio?

[rayna_057]

Hi @Victor Chen , great article! i'm following the 'Embed the Virtual Agent web client in an external web page (legacy method)' to embed virtual agent as an iframe, i configured the system properties as needed and embedded it in my webpage, however the virtual agent only works when i am logged into ServiceNow, is there a way virtual agent in a webpage can work without a user having to log into servicenow? your help will be very much appreciated.

https://docs.servicenow.com/bundle/washingtondc-servicenow-platform/page/administer/virtual-agent/ta...

[Shweta Beedkar]

Hi @Victor Chen I have configured VA in  ServiceNow. I have topics configured in it. Will same topics come in external page when embedded by using legacy method? If not, then where to configure those topics?

[Victor Chen]

@Shweta Beedkar - for each topic you wish to display externally for 'guest' users, the topic visibility in the 'Properties' tab. 

[Tang Phat]

Hi Victor, thank you for you article.

However, when I tried to embed VA in external website using new method in Tokyo. It said that some JS file not found and "ServiceNowChat is not define".

Could you please help me assists with this?

Thank you very much

[vivek_chudasama]

Hi @Victor Chen , 

Great Article! I have a follow up question. 

Can we configure seperate greeting for external webpage VA OR Can we trigger specific topic in external webpage using topic_id context variable, please assist how we can achieve this, thanks!

Thank you very much!

[nathandanek]

Hi @Victor Chen 

If we have moved from the virtual agent widget to the service portal agent chat, is this still possible? Curious if you can embed the agent chat in another webpage. 

https://www.servicenow.com/docs/bundle/xanadu-platform-user-interface/page/build/service-portal/task...

Thanks,

Nathan

[ayman_h]

@Victor Chen thanks for this. The Chatbot has disappeared from the demo website. Can you please confirm if the chatbot can be minimised to the circle icon after it has been expanded just like you can on the ESC portal?

Regards,

Ayman

[Rajiv Handa]

You may need to add another CORS rule in ServiceNow related to API: Advance Chat Settings [now/advance_chat_settings], if you are getting the following error:

 Access to fetch at 'https://xxxx.service-now.com/api/now/advance_chat_settings/get_feature_status' from origin 'https://www.xxxx.abc.com' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: The value of the 'Access-Control-Allow-Credentials' header in the response is '' which must be 'true' when the request's credentials mode is 'include'.