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 Agent 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 uniquely your brand. The following steps give you everything you need to add an AI agent widget to your web app.

To incorporate AI automations or other features that don't use a chat interface in a frontend, see Squid AI Agents.

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 "AI Agents" 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 Add agent. Each AI agent can have a persona or use case, distinguished by its own set of instructions and context. This enables customized responses from the AI agent according to the specific settings.
When creating the new agent, create a agent ID that is a unique identifier for the agent.
Select an AI model for the agent from the Model name dropdown.
Toggle on Set agent to public so that all users are able to use the widget.
Click Add to add the AI agent.

After adding the agent, continue by adding your own instructions and context 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.
Context: context provides the agent with additional background knowledge. It allows the agent to provide relevant answers on specific topics that may not be part of the underlying AI model. Context can be added using URLs, 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 six placeholders with your own project's values which are available in the console. header-title controls the header text at the top of the widget, and intro-text controls the introductory message sent to the user:

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' {/* choose one of 'dev' or 'prod' */}
   squid-ai-integration-id='ai_agents'
   squid-ai-profile-id='AI_AGENT_ID'
   header-title='YOUR_HEADER'
   intro-text='YOUR_MESSAGE'
   squid-developer-id='YOUR_DEVELOPER_ID' {/* Include the developer ID when running backend locally */}
/>

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>

squid-ai-functions: provide a comma-separated list of Squid AI functions, allowing your AI agent to take actions based on the client prompt. For more information on Squid AI Functions, view the AI Functions documentation
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.
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-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.
class: the widget has two options for general styling, squid_chat_widget_dark and squid_chat_widget_light.
enable-transcription: a boolean indicating whether to include a microphone icon that enables the user to speak their prompts and have them automatically transcribed.
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'
  }}
/>

To connect your AI agent widget to a locally running Squid backend, include the squid-developer-id parameter in your widget:

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' {/* choose one of 'dev' or 'prod' */}
   squid-developer-id='YOUR_DEVELOPER_ID'
   squid-ai-integration-id='ai_agents'
   squid-ai-profile-id='AI_AGENT_ID'
   header-title='YOUR_HEADER'
   intro-text='YOUR_MESSAGE'
/>

When you're ready to deploy your app, ensure that you remove the squid-developer-id parameter from your frontend.

Access control

To manage access to your widget, integrate your auth provider with 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, then 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 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);
}

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 our other features of Squid AI 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

Adding the Squid AI Agent widget to your site

Enabling custom elements

Optional customization

Running the widget locally

Access control

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​

Adding the Squid AI Agent widget to your site​

Enabling custom elements​

Optional customization​

Running the widget locally​

Access control​

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

Setting up the AI Agent

Adding the Squid AI Agent widget to your site

Enabling custom elements

Optional customization

Running the widget locally

Access control