> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syllable.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Web Chat
> How to embed and customize the AI chat widget on a website.
The Syllable Web Chat is an embedded, secure web chat application designed for integration on registered third-party domains. It provides seamless communication by maintaining the session across different pages under the same domain. This web chat can be customized to reflect the client's branding and specific needs, ensuring a tailored user experience. You can see the web chat in action by clicking the Syllable logo in the bottom right corner of [our website](https://syllable.ai/).
To properly configure the web chat, the following parameters are required:
* **Domain Address**: The domain where the web chat will be deployed.
* **Client Id**: A unique key that identifies a specific Syllable AI target. For information on how to create a Client Id, please contact Syllable AI support at [support@syllable.ai](mailto:support@syllable.ai).
To register a web chat instance, please reach out to [support@syllable.ai](mailto:support@syllable.ai).
## Installation
You have two options for installing Syllable Web Chat:
#### NPM
To install via NPM, run the following command:
`npm install @syllableai/webchat`
#### CDN
To include the web chat directly from our CDN, use the following script tag. Replace \[VERSION] with the specific version you want to use (e.g., 1.0.0):
``
Alternatively, you can use the latest version:
``
## Usage
You have two options for using Syllable Web Chat. For either method, you should replace 'MY\_CLIENT\_ID'with your valid Client ID.
### NPM using JavaScript or Typescript
```javascript theme={null}
import SyllableWebChat from '@syllableai/webchat';
const webChat = new SyllableWebChat({
clientId: 'MY_CLIENT_ID'
});
webChat.init();
```
### CDN directly in HTML
Add this script above the HTML `` element:
```javascript theme={null}
```
Be sure to include both closing HTML script tags
### Add Optional Container
Optionally, add a div container to your HTML where the Syllable Web Chat will be rendered (if not specified, Syllable Web Chat will be appended to the bottom of HTML body tag):
``
You may need to adjust the z-index of this div container based on your layout.
## Additional configuration
The Syllable Web Chat can be extensively configured to meet your specific requirements. For additional configuration, please contact Syllable AI support at [support@syllable.ai](mailto:support@syllable.ai). Below are the available parameters that can be customized:
Set `embed_mode` to `true` to hide the iframe-internal header (the dark band with the minimize button) when wrapping the chat in your own window chrome.
```json theme={null}
{
"session_timeout_m": 10080,
"header_title": "Company Name",
"header_subtitle": "Virtual assistant",
"info_text": "Disclaimer: This chat feature is not intended for use in medical emergencies or for medical advice. If you are in need of immediate medical attention, contact your provider or call 911.",
"info_button_label": "Close",
"info_button_bgcolor": "#1d4f91",
"info_button_bgcolor_hover": "#1d4f91",
"message_required": "Please type your message",
"input_placeholder": "Type your message here...",
"header_bgcolor": "#1d4f91",
"embed_mode": false,
"chat_button_bgcolor": "#1d4f91",
"chat_button_bgcolor_hover": "#1d4f91",
"chat_button_image_url": "https://cdn.syllable.ai/webchat/...",
"header_image_url": "https://cdn.syllable.ai/webchat/...",
"chat_agent_bubble_bgcolor": "#C0D5F0",
"chat_user_bubble_bgcolor": "#D9DCE1",
"chat_error_bubble_bgcolor": "#991A1C",
"chat_error_bubble_start_session": "Start a new conversation",
"chat_error_bubble_failed_message": "Failed to send message. Please try again or start a new conversation.",
"session_expired_label": "Conversation expired",
"session_ended_label": "Conversation ended",
"start_session_button_label": "Start conversation"
}
```
## Web cards
Syllable offers graphical web cards to display structured data in a rich, visual format within the Web Chat channel.\
To enable this, your tool must call an endpoint that returns a card-formatted response, which Web Chat then renders as a card UI.
### Tool definition requirements
The tool definition requires the following to function:
* It must have **“propagate\_tool\_result”** value set to **true** in order for the result to be passed to Web Chat
```json theme={null}
"options": {
"propagate_tool_result": true
}
```
### Reponse format
Your endpoint must return data in the following response format:
* The **“result”** object must have attribute **“type”** with value **“card”** for the chat to identify that the results are meant to be displayed in the form of the Card
* The results can have a list of cards to be displayed contained under **“list”**, each being defined by the following schema:
```json theme={null}
{
"type": "card",
"list": [
{
"media": {
"imageUrl": "https://example-image.jpg",
"originalImageWidth": 400,
"originalImageHeight": 200,
"maxHeight": 300
},
"content": {
"header": "Test Doctor, MD",
"subheader": "Test Specialty",
"description": "Test Expertise 1, Test Expertise 2",
"contentAlwaysLeft": false,
"avatarImageUrl": "https://example-image-square.jpg"
},
"actions": [
{
"type": "text",
"text": "Distance: 0.6 miles"
},
{
"type": "link",
"text": "(415) 555-1234",
"icon": "phone",
"link": "tel:4155551234"
},
{
"type": "link",
"icon": "chat",
"link": "https://www.google.com"
},
{
"type": "button",
"text": "Book Appointment",
"link": "https://www.google.com"
}
],
"cta": {
"text": "View Profile",
"icon": "arrow",
"link": "https://www.google.com"
}
}
]
}
```
### Card object schema
Card can be composed from the individual sections, each section is **optional**:
* **media** - top banner or standalone image
* **imageUrl** - required path to the image
* **originalImageWidth, originalImageHeight** - optional dimensions for preserving aspect ratio, if not specified the image will be contained in the square and filled using cover background style, the image will scale to fill the available space
* **maxHeight** - maximum height of the image useful for banners to maintain the fixed height
* **content** - content area where description is visible, usually avatar of the person like a provider with name, title, specialty
* **header**
* **subheader**
* **description**
* **avatarImageUrl** - optional path to avatar image, will be rendered in circle container, if not provided it won’t be visible, if provided as empty string “” it will render image placeholder, if not provided it will adjust the space to accommodate headers and description better
* **contentAlwaysLeft** - aligning content always to the left, by default the content on smaller screens is center aligned
* **actions** - multibutton and option panel where more controls and structured information can be added like, text, buttons, links
* **type** - available options: **text**, **button**, **link**
* **text** - optional text to be displayed, if there is an icon instead it will just show icon button
* **icon** - optional icon that will appear on the left side of **text** specified, possible values: **phone**, **email**, **chat**, **calendar**, **arrow**
* **link** - link url
* **cta** - bottom main button
* **text** - optional text to be displayed, if there is an icon instead it will just show icon button
* **icon** - optional icon that will appear on the left side of **text** specified, possible values: **phone**, **email**, **chat**, **calendar**, **arrow**
* **link** - link url
### Tool definition example:
This is an example tool that queries an endpoint for a service provider and returns the data in a format to display as a card.
```json theme={null}
{
"type": "endpoint",
"tool": {
"type": "function",
"function": {
"name": "provider_card",
"description": "Get a display card for a service provider.",
"parameters": {
"type": "object",
"properties": {
"provider_name": {
"type": "string",
"description": "The name of the provider to search for."
},
"location": {
"type": "string",
"description": "The location to search for providers."
}
},
"required": []
}
}
},
"endpoint": {
"url": "https://your-endpoint-here",
"method": "get",
"argument_location": "query"
},
"defaults": null,
"static_parameters": null,
"result": null,
"options": {
"propagate_tool_result": true
}
}
```
### **Common use cases**
Card configuration allows the following to show:
* Standalone image - use **media**
* Provider, location card - use **content** and **cta** and optionally **actions**, for full mode combine with **media**
* Structured text with header and content - use **content** with **header** and **description**
* A visible button - use **cta** pointing to the link url alternatively **actions** with 1 or more entries