Incorporate an AI chat widget

If you're looking to incorporate the power of an AI agent into your application but are unsure where to start, Squid's AI chat widget provides an option that is approachable enough to spin up in just a matter of minutes while being powerful enough to give a customized experience to your users that is unique to your business. The following steps give you everything you need to add an AI chat widget to your web app.

Setting up the AI Agent

Navigate to the Squid Console and create a new application. This Squid application will contain your AI widget.
Navigate to the Agent Studio tab in the Squid Console.

Note

Squid provides two different target environments for development and production. For the agent to work, ensure that you are using the same target environment throughout the project as agents are not shared across environments. Learn more about Squid's environments here.

Click Create New Agent. Each AI agent has a unique persona, distinguished by its own set of instructions and abilities. This enables customized responses from the AI agent according to the specific settings.
Provide a descriptive name for your agent in the Agent ID field. Note: This ID cannot be changed afterward. Example: "ACME business analyst".
Add a detailed description of what your agent does, for future reference. Example: "Queries and emails my ACME home goods business data."
Click Create to initialize your new agent.

After adding the agent, continue by adding your own instructions and knowledge to personalize this agent.

Instructions: instructions provide rules for how the agent responds. Instructions work best as direct and simple guidelines. For example, good instructions could include directing Squid AI to respond concisely or to provide specific responses to certain types of questions.
Knowledge base: items added to the knowledge base provide the agent with additional background context. It allows the agent to provide relevant answers on specific topics that may not be part of the underlying AI model. Knowledge can be added using files or raw text. Some good examples for context could include documentation, product manuals, and business operations (e.g store hours).

You can test how your unique agent responds to messages by clicking on the Test chat button.

To add the Squid AI chat widget to your website, add the following in the <head> or <body> sections of your HTML:

Client code
<script async src="https://widget.squid.cloud/widget.umd.js"></script>

There are two options for embedding the chat widget into your website's HTML code:

Use <squid-chat-widget /> for a standard chat widget that is displayed on the screen. This HTML element functions as a standard block element that can be placed anywhere in the <body> of your HTML.
Use <squid-chat-widget-with-fab-button /> for a chat widget with a floating action button that toggles the chat open and closed. This HTML element can be placed anywhere in the <body> of your HTML, and the floating action button will appear in the bottom right corner of the screen.

To complete the widget's configuration, add the following attributes to the widget's HTML element. Replace the first five placeholders with your own application's values. You can find the first four values in the Backend Project section of the application overview page in the Squid Console by clicking on Show env vars:

Client code
<squid-chat-widget
   squid-app-id='YOUR_APP_ID'
   squid-region='YOUR_REGION' {/* example: 'us-east-1.aws' */}
   squid-environment-id='dev | prod' {/* one of 'dev' or 'prod' */}
   squid-developer-id='YOUR_DEVELOPER_ID' {/* Include the developer ID when running backend locally */}
   squid-ai-profile-id='AI_AGENT_ID' {/* The ID of the AI agent you created (step 4 above) */}
   squid-ai-integration-id='ai_agents'
/>

Enabling custom elements

Some frontend frameworks require an additional step for allowing the usage of custom HTML elements. The following describes this process for React and Angular. If you are using a different frontend framework, be sure to research how to enable custom elements for your use case.

React: you can enable the Squid AI HTML elements in React by placing the following declarations.d.ts file under the src directory:

Client code
declare namespace JSX {
  interface IntrinsicElements {
    'squid-chat-widget-with-fab-button': any;
    'squid-chat-widget': any;
  }
}

Angular: you can enable custom HTML elements in Angular by placing the following code in your src/app/app.module.ts file:

Client code
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})

You now have the Squid AI Agent widget live on your site!

Optional customization

The Squid AI widget also has optional parameters to customize your widget for your use case:

menu-items-json: accepts an array of objects with title and slotName attributes. This array describes the title and name of dropdown menu items to be defined as children of the widget. The dropdown menu will appear in the top right of the widget. The following is an example using JSX:

Client code
<squid-chat-widget

  // ...

  menu-items-json=[{"title": "Contact us", "slotName": "contact"}]
>
  <div slot="contact">
    <form onSubmit={onSubmit} >
      <input type="email" />
    </form>
  </div>
</squid-chat-widget>

header-title: controls the header text at the top of the widget
intro-text: controls the introductory message sent to the user
squid-ai-functions: provide an array of strings of Squid AI function names, allowing your AI agent to take actions based on the client prompt. For more information on Squid AI Functions, view the AI Functions documentation
disable-history: a boolean indicating whether to keep or disable conversation history.
include-reference: a boolean indicating whether to include in its response a reference to the context the AI Agent used to answer the query.
squid-ai-query: when set to "true", the widget defines the squid-ai-integration-id as the integration ID for your database. When using this parameter, set squid-ai-profile-id to "undefined". For more information on querying your data sources with natural language, view the Query with AI documentation.
squid-ai-max-tokens: the maximum number of tokens to pass to the LLM. This advanced feature can be used to change the quality and cost of responses.
squid-ai-temperature: The randomness of responses on a scale from 0 to 1.
squid-ai-context-metadata-filter: a JSON string indicating the metadata filter to apply to the context. For more information on context metadata filtering, view the documentation.
enable-transcription: a boolean indicating whether to include a microphone icon that enables the user to speak their prompts and have them automatically transcribed.
open-on-load: a boolean indicating whether the widget with FAB button should be open when the component renders.
squid-ai-override-model: use this option to override which LLM model the agent uses.
class: the widget has two options for general styling, squid_chat_widget_dark and squid_chat_widget_light. More customization options are available in the style section below.
style: the widget can be styled using the HTML element's style attribute. In addition to standard options such as width and height, the Squid AI chat widget has multiple CSS variables which can be used to control the widget's styling. The following is a list of available variables:
- --squid-widget-ai-message-background-color
- --squid-widget-avatar-image-url
- --squid-widget-body-background-color
- --squid-widget-header-background-color
- --squid-widget-header-menu-button-background-color
- --squid-widget-header-menu-button-icon-url
- --squid-widget-header-menu-item-color
- --squid-widget-header-menu-item-hover-background-color
- --squid-widget-header-title-color
- --squid-widget-inline-code-background-color
- --squid-widget-inline-code-border-color
- --squid-widget-link-color
- --squid-widget-powered-by-color
- --squid-widget-textarea-background-color
- --squid-widget-textarea-border-color
- --squid-widget-textarea-text-color
- --squid-widget-textarea-submit-image-url
- --squid-widget-user-message-background-color
- --squid-widget-user-message-color
- --squid-widget-fab-background-color
- --squid-widget-fab-image-url
- --squid-widget-fab-close-image-url
- --widget-width

The following is an example using the style parameter. Alternatively, you can define these variables in an external CSS file:

Client code
<squid-chat-widget

  ...

  style={{
    '--squid-widget-header-background-color': '#fcba00',
    '--squid-widget-body-background-color': '#999999'
  }}
/>

Access control

There are two access control modes for an AI agent – public and private.

A public agent can be accessed by anyone. You can set your agent to public in the Squid Console by navigating to the Agent Studio tab, selecting your agent, and clicking on Agent Settings. Scroll down to toggle the agent to public.

If your agent is set to private, you must manage access to your widget. Start by connecting your auth provider to Squid, and then pass your integration ID and the client's auth token to the widget's squid-auth-provider parameter:

Client code
<squid-chat-widget
{/* ... */}
squid-auth-provider={JSON.stringify({
  integrationId: "AUTH_INTEGRATION_ID",
  token: "AUTH_TOKEN",
})}
/>

This gives your Squid backend access to your auth credentials. The following example allows users to chat with all AI agents if they are authenticated:

Backend code
@secureAiAgent('chat')
allowAccessToAgent(): boolean {
  return this.isAuthenticated();
}

Note

When an AI agent is set to public in the Squid Console, this bypasses the @secureAiAgent rules and allows anyone to chat with the AI agent. However, while any client can chat with the AI agent, the auth credentials are still available in the Squid backend and can apply to any AI functions. This means you can still protect some access to the functionality of public AI agents.

Auth credentials are also accessible in AI functions, allowing you to manage fine-grained access to each function attached to an AI agent. You can use the auth credentials to ensure the client is logged in, check for the presence of required custom claims on the client's token, or query data sources based on the credentials.

The following example shows accessing the client user credentials to get the user's Slack user ID. This user ID is then passed to a function that searches for Slack messages that the user is permitted to access.

Backend code
@aiFunction('', [
    {
      name: 'query',
      type: 'string',
      description: 'The search term to look for in Slack.',
      required: true,
  },
])
async querySlack(data: { query: string }) {
  const userId = this.getUserAuth().userId;
  const { slackUserId } = await this.squid.collection('slack_users')
    .doc({ userId: userId })
    .query()
    .dereference()
    .snapshot();
  if (!slackUserId) {
    return 'Not Authorized';
  }

  return await this.searchSlackMessages(query, slackUserId);
}

Next Steps

And that's it! You now know how to deploy Squid's powerful AI chat widget on your website.

To find out more about what Squid AI can do, check out other features like Query with AI and more customization options with Squid AI assistant.

You can also try out samples with our tutorials, including:

Incorporate an AI chat widget

Integrate an AI-powered chat widget into your website, enabling users to easily understand your business value.

Setting up the AI Agent

How to add the AI chat widget to your site

Enabling custom elements

Optional customization

Access control

Next Steps

Integrate an AI-powered chat widget into your website, enabling users to easily understand your business value.​

Setting up the AI Agent​

How to add the AI chat widget to your site​

Enabling custom elements​

Optional customization​

Access control​

Next Steps​

Integrate an AI-powered chat widget into your website, enabling users to easily understand your business value.

Setting up the AI Agent

How to add the AI chat widget to your site

Enabling custom elements

Optional customization

Access control

Next Steps