Deploying Chat Agents (Chatbots)

Symphona Converse provides flexible options to deploy your AI-powered chat agents seamlessly into your existing applications or websites. You can choose between a straightforward embedding solution, which integrates chat agents directly into your user interface with minimal coding, or utilize our robust REST API, offering advanced customization and integration capabilities for more complex scenarios.

Widget Integration

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.

‣

Edited Video Transcript

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".

Chatbot Appearance: Change the colour of the background, where the chat messages will appear. Change the colour of the footer, where chat buttons appear.
Upload a Background Header Image: If desired, this allows the user to upload an image for their Header instead of a colour. The image will always override the selected Header Colour.

Upload an Agent 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.
Corner Roundness: Modify how rounded the corners of the chat widget are.
Preview Message: If set to the First Received Message, this means the preview bubble will show the first message sent by the agent in the live chat widget. If set to Custom Message, it will display a custom message instead.
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.

Example of Chat Widget Embedding Code

The first snippet of code runs a script that lets the website hosting service know a Agent will be running on the website. You’ll paste this first snippet in the following areas of your website:

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.

The second snippet of code is a piece of HTML code that contains the Chat Widget. You’ll paste this within the <body> tag of your website.

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

You can configure the height, width, and dropshadow of a Symphona Agent.

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.

Embed code to a WordPress post or page

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.

Embed code to a WordPress template

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 tab
2. 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!

REST API Integration

Symphona allows you to easily initiate and manage conversations between your users and AI-powered agents using our REST API.

This guide walks you through the basic steps to start, continue, and end a chat session with your AI Agent. You’ll learn:

Which endpoints to call
How to format your requests (headers, body, etc.)
Common response formats and usage notes

By the end, you’ll be able to seamlessly integrate the AI Agent’s chat functionality into your own application or workflow.

For specific API details, please refer to the documentation.

Prerequisites

API Base URL – https://app.symphona.ai/dashboard/api.
Authentication – Deployments need an API key. Header must include apiKey .

Start a Chat Session

Using this API request, you will be able to start a conversation with an AI Agent.

The minimum required information you must give the API to start a conversation are:

channelType - “Webchat” for any external widget integration
channelName - Widget name
targetSymphonaAgentID - The agent you want to talk to. Must exist in Symphona.

To find your AgentID, press the Edit Agent for the Agent you want to use. At the top of the page, you will find it’s ID.

userId - Your own identifier for this end‑user

Request URL & Method:

POST "https://app.symphona.ai/dashboard/api/v1/conversation/startSession"

Example Request Body:

{
  "channelType": "Web Chat",
  "channelName": "Demo",
  "targetSymphonaAgentID": "0201f741-cdeb-45c9-a12e-xxxxxxxxxxxx",
  "userID": "user111"
}

Example Response Body:

{
    "conversationSessionID": "75ec2816-12fd-4e97-a0a5-xxxxxxxxxxxx"
}

With this response, it means your conversation has started!

Send a Message

Using this API request, you will be able to message with an AI Agent. You will also receive a message back!

The information you must give the API are:

conversationSessionID - SessionID that you got from the startSession API
message - Message you want to send to the AI Agent

Request URL & Method:

POST "https://staging.app.symphona.ai/dashboard/api/v1/conversation/sendMessage"

Example Request Body:

{
  "conversationSessionID": "75ec2816-12fd-4e97-a0a5-xxxxxxxxxxxx",
  "message": "How are you doing today?"
}

Example Response Body:

{
    "response": "I'm just a program, so I don't have feelings, but I'm here and ready to help you with whatever you need! How can I assist you today?"
}

You can call sendMessage repeatedly to create a multi‑turn conversation—always supply the same conversationSessionID.

End the Session

Using this API request, you will be able close the messaging session with an AI Agent.

The information you must give the API are:

conversationSessionID - SessionID that you have been messing the AI Agent with

Request URL & Method:

POST "https://staging.app.symphona.ai/dashboard/api/v1/conversation/endSession"

Example Request Body:

{
  "conversationSessionID": "75ec2816-12fd-4e97-a0a5-xxxxxxxxxxxx"
}

Example Response Body:

{
    "OK"
}

Why end? It closes server‑side resources and provides a clear point for analytics.

With that, you can now use Symphona AI Agents within your own widgets!