Deploying Chat Widget Agents (Chatbots)
With Symphona, you can create automated Agents and embed them anywhere within your website. In this tutorial, we’ll go over:
- How to create a Chat Widget and assign your Agent to it
- How to customize your Chat Widget as either a popup Agent or a frame Agent
- How to customize the dimensions of your Agent
- How to embed your Chat Widget within any website hosted on WordPress, Webflow, Wix and Shopify
Let’s dive in!
Tutorial Video
Follow along with us as we design a Chat Widget and link it to our Agent, ready to be embedded on an existing web page.
Creating Your Chat Widget
- Navigate to Chat Widgets: Go to the Settings tab in Symphona. From there, proceed to the Front Office section and click on Chat Widgets.
- Create a New Widget: You will see a list of existing chat widgets. Click the Create New Widget button on the top right. This action will prompt you to name your new widget. Enter a name, for example, "New Widget 2".
- Provide a Description: Optionally, you can provide a description for your widget. While this step is not mandatory, it can be helpful for future reference.
- Assign an Agent: Scroll to the Agents section. You can choose what agent you want to assign to your widget here.
- Customize the Appearance: Scroll down to the Appearance section where you can start styling your chat widget. This includes changing the logo, background colors, text box colors, and button colors to match your brand. Use the eyedropper tool to select specific colors. For instance, you may choose a light blue for secondary colors to keep the design on-brand.
- Adjust the Header: In the Header section, you can choose to include or exclude text. You may decide to leave the header empty if you don't need any header text or subtext.
- Configure Icons: Scroll further to Icons. This section is responsible for the appearance of the widget when it's collapsed. You can customize the background color and text color to ensure good contrast and visibility. For example, you might choose an orange notification icon to catch users' attention.
- Name the AI Agent: In the same section, you have the option to change the name of the messages coming from the AI agent. By default, the name is "SimplyBot", but you can change this to fit your company's branding, such as "PharmaBest AI".
- Upload an Icon: If desired, you can upload a custom icon for your AI agent. This gives you an opportunity to further personalize the widget to match your brand identity.
- Enable File Upload: Decide whether or not to enable file upload functionality. For fully automated chats, this option is often unnecessary and is turned off by default. Enable it if your specific case requires it.
- Save Changes: Once you have completed all the customizations to your satisfaction, click on Save Changes. This will finalize the creation of your new chat widget.
By following these steps, you will successfully create a custom chat widget tailored to your brand and ready for deployment on your website.
Installing Your Chat Widget
Once you have a Chat Widget created, head to Agent Manager, find the Agent you would like to deploy as a chatbot, and click on its Settings icon in the top right of the Agent card. When the Agent detail card opens, click on Configure Channels, and then Add Widgets. Once you select your desired Chat Widget, click Add.
You should now see a new Chat Widget in the listed of Assigned Chat Widgets and blue text with the prompt Install Chat Widget - click on this.
You will now see two snippets of code. These code snippets are unique to your Agent Chat Widget and is what you add to your existing website to have the Chat Widget appear.
- If your website is a Server-Side Rendered (SSR) application, paste into the <body> tag of your website.
- Some examples of SSR websites: WordPress, Wix
- If it is not a SSR application, paste it into the <head> tag of your website.
- Some examples of non-SSR websites: Webflow, Shopify
- If you’re unsure whether your website is an SSR application or not, try pasting it into one section and then the other to see which one works.
Embedding Widget as Popup vs. Frame
Your Agent widget can appear as either:
- A popup that can be accessed throughout your entire website and will be minimized when not in use, or
- A frame that will be embedded within a certain section of a website page and is always visible on that page
You can choose how you want your Agent to display based upon:
- How you set its display style
- Where you place the Agent embed code within the <body> tag
Let’s look at the following example embed code for more details:
<div class="simplyask-agent-widget"
data-iva-agent-id="ef4d4035-350b-4d7a-991d-7e5bcda9990c" (Example Agent ID)
data-widget-id="ed956d4b-bead-41e1-a808-54527608c801" (Example Chat Widget ID)
data-display-style="frame" ("frame" makes it appear as a frame; "popup" makes it appear as a popup)
data-width="800px" (Agent width)
data-height="500px" (Agent height)
data-box-shadow="1px 1px 10px 2px rgba(0, 0, 0, 0.9)" > (Dropshadow)
</div>Setting the parameter data-display-style to “popup” will make the Agent widget appear as a popup throughout your entire website.
Setting the parameter data-display-style to “frame” will make the Agent widget be embedded within the section of the website you pasted the embed code to. The Agent will then appear as a frame within that section, always visible.
How to Embed a Popup Agent
- Set data-display-style to “popup” in the embed code.
- Paste the code anywhere in the <body> tag of your website.
How to Embed a Frame Agent
- Set the parameter data-display-style to “frame”.
- Paste the second code snippet within the <body> tag in a section of your choice. Note that for frame Agents, the Agent will appear in the section of the website page you paste it into.
- Once your website runs the updated code, the Agent widget should now appear as a frame in the section of the website page where you pasted the embed code.
Configuring Agent Dimensions
Symphona Agents work within any part of your website. However, if you are embedding a Agent as a frame within a section of your website, its physical dimensions will need to fit within its parent container. Otherwise, the Agent will break and not appear.
Symphona Agents come with default height, width, and dropshadow for frame Agents, so they will work on your website without further customization.
Here are some notes on configuring the Agent dimensions and some recommendations on the ideal height, width and dropshadow:
- The default height will always be the height of the parent container.
- The default width will always be the width of the parent container.
- We recommend setting a pixel height for their parent container. Otherwise, the chat height could be too big or too small.
- The recommended height is 500px.
- The recommended width is the width of the parent container (note: since the default width will always be the width of the parent container, we recommend not changing the default)
- You can customize the height and width of your Agent, but neither can go lower than 300px. Doing so will break the widget.
- No dropshadow is the default setting. However, you can add and customize any dropshadow for your Agent, including intensity and colour, via CSS in box-shadow format. The recommended dropshadow is below:
box-shadow: 1px 1px 10px 2px rgba(0, 0, 0, 0.10);For more details on how each parameter works within the embed code, you can expand the technical details below:
Embed Code Technical Documentation
If you want to know more about the embed code, here are all the parameter details.
Attribute | Default Value | Possible Value(s) | Mandatory |
class | null | "simplyask-agent-widget" | Yes |
data-iva-agent-id | null | "ef4d4035-350b-4d7a-991d-7e5bcda9990c" | Yes |
data-widget-id | null | "ed956d4b-bead-41e1-a808-54527608c801" | Yes |
data-display-style | "widget" | "widget" || "frame" | No |
data-width | If data-display-style === "frame",
then default = "100%",
else default = "346px" | {Any dimension} | No |
data-height | If data-display-style === "frame",
then default = "100%",
else default = "665px" | {Any dimension} | No |
data-box-shadow | If data-display-style === "frame",
then default = "none",
else default = "1px 1px 10px 2px rgba(0, 0, 0, 0.1)" | {Any Box Shadow} | No |
Embedding Your Agent on Your Website
We’ll now go through how to do this on four popular website hosting platforms: WordPress, Webflow, Wix, and Shopify.
Embedding Your Agent on WordPress
Since WordPress is an SSR application, we just have to paste both code snippets in the <body> tag of your WordPress post, page, and/or website.
- In your WordPress dashboard, go to your posts or pages.
- Create a new post or page, or edit an existing one.
- Inside the block editor, click the + button, search for Custom HTML, and then click to insert a Custom HTML block.
- Paste both code snippets into the text field provided by the Custom HTML block. If this doesn’t work, create two Custom HTML blocks and place one code snippet in each block.
- You can play around with how the Agent widget looks on your page. Click Preview on the block toolbar to see what the final result will look like.
- Once you’re finished, click either the Save Draft, Preview, or Publish button.
Note: If you use WordPress's Classic Editor Plugin, then instead of using a Custom HTML block, change the text editor from Visual to Text mode and paste the embed code in the editor.
If your WordPress theme supports the site editor, then you can embed code to your site’s templates.
Steps:
- In your WordPress dashboard, go to the Editor and navigate to a template of your choice.
- Inside the block editor, click the + button, search for Custom HTML, and then click to insert a Custom HTML block.
- Paste both code snippets into the text field provided by the Custom HTML block. If this doesn’t work, create two Custom HTML blocks and place one code snippet in each block.
- You can play around with how the Agent widget looks on your page. Click Preview on the block toolbar to see what the final result will look like.Paste both code snippets into the text field provided by the Custom HTML block.
- Once you’re finished, click either the Save Draft, Preview, or Publish button.
Embedding your Agent on Webflow
Since Webflow is not an SSR website, we need to place the first and second code snippets in the <head> tag and <body> tag of your website respectively.
Webflow University has this tutorial on adding code to <head> and <body> tags in your website, including for specific pages or throughout your website.
You’ll likely want your Agent to be available no matter where the user is on the website, so we’ll share steps on how to do that. If you only want it to show up on specific pages, the Webflow tutorial also offers steps on page-specific embedding.
Here’s what the tutorial says on adding the first code snippet from Symphona:
1. Visit Site settings > Custom code tab2. Add your custom code in the Head code section
3. Click Save Changes.
To add the second code snippet, apply it to the Footer section.
Code entered in the Footer code section appears before the closing </body> tag in your site’s HTML markup and applies to your entire site.To add custom code to the Head tag:
1. Visit your Site settings → Custom code tab.
2. Add your custom code in the Footer code section.
3. Click Save Changes.
Embedding your Agent on Wix
Since Wix is an SSR application, we just have to paste both code snippets in the <body> tag of your Wix website.
Wix offers this tutorial on embedding code within your website. You’ll need to follow the steps twice, once for each code snippet.
To add both code snippets, follow the Wix tutorial. At Step 6, choose whatever option you prefer for your Agent (we recommend All Pages). At Step 7, select either Body - start or Body - end.
As the tutorial suggests, make sure to give your code snippets unique and recognizable names so you can identify them later. Note that your website must be published with an active domain to add a Agent.
Embedding your Agent on Shopify
In your Online Store, go to your theme. Click on the More Options button (the three dots next to Customize) and select Edit code.
Click Edit code to access the theme files. Open the Layout folder, then open theme.liquid.
Note that if you’ve made modifications to your theme, theme.liquid might not be the file to adjust. There might be additional layout files to modify.
Within theme.liquid, search for the opening and closing head tags (<head> and </head>). Paste the first code snippet anywhere in between the <head> tags.
Search for the opening and closing body tags (<body> and </body>). Paste the second code snippet anywhere in between the <body> tags.
Save your changes once you’re done!
- Deploying Chat Widget Agents (Chatbots)
- Tutorial Video
- Creating Your Chat Widget
- Installing Your Chat Widget
- Embedding Widget as Popup vs. Frame
- How to Embed a Popup Agent
- How to Embed a Frame Agent
- Configuring Agent Dimensions
- Embed Code Technical Documentation
- Embedding Your Agent on Your Website
- Embedding Your Agent on WordPress
- Embedding your Agent on Webflow
- Embedding your Agent on Wix
- Embedding your Agent on Shopify