The FigoChat Web SDK adds a ready-made AI chat to websites and web apps: Angular, React, Next.js, Vue or plain HTML. A chat button appears in the corner of the page. It opens a chat window where customers can type, send voice notes and upload files (images are read with OCR). When a live agent takes over, the agent's replies appear in the same chat. The chat uses your brand color, and the conversation runs against your FigoChat assistant. | |
|---|
| Package | @figoailabs/figochat-web on npm |
| Works with | Angular, React, Next.js (App Router and Pages Router), Vue, Svelte or plain JavaScript |
| Browsers | Current Chrome, Edge, Firefox and Safari, on desktop and mobile |
| Size | About 58 KB gzipped, including the live agent client |
The chat is drawn in its own Shadow DOM, so your site's CSS doesn't change it and its CSS doesn't leak into your site. It doesn't depend on any framework.Building a mobile app? Use the FigoChat Mobile SDK guide instead (React Native, Flutter, Capacitor/Ionic, Android and iOS).
1. Before you start#
1.
An API key. Click API Keys in the sidebar, then Create API Key, enter a name such as Website, and copy the key. It's shown only once.
2.
An assistant ID. Click AI Chatbots in the sidebar, open your chatbot, and click the copy button next to Assistant ID.
3.
AI credits. The company needs at least 0.02 credits (see Billing), or every call returns 401 Insufficient AI credits.
Security: a browser app sends its API key with every request, so anyone can read it in the page source or the browser's network tab. Create a key just for your website, so you can delete it without breaking your other integrations. If it's misused, delete it under API Keys and deploy your site with a new key. For stronger protection, have your backend hand the key to the page only after the customer signs in.
2. Install#
Or, on a site without a build step, load it from a CDN. The script defines a global FigoChat:
3. Initialize#
Call FigoChat.initialize once in the browser, for example after the customer signs in. The chat button appears in the bottom-right corner.import { FigoChat } from '@figoailabs/figochat-web';
FigoChat.initialize({
apiKey: 'YOUR_API_KEY',
assistantId: 'YOUR_ASSISTANT_ID',
fullName: 'Ada Lovelace',
emailAddress: 'ada@example.com',
mobilePhone: '+2348012345678',
primaryColor: '#F97316',
// optional: send the customer's first question for them
firstCustomerMessage: 'Where is my order #1042?',
});
Call it again whenever the customer or the settings change. It replaces the previous chat.Options#
| Option | Type | Required | Default | Description |
|---|
apiKey | string | Yes | – | API key from API Keys in the FigoChat admin. Sent as Authorization: Bearer <apiKey>. |
assistantId | string | Yes | – | AI Chatbots → your chatbot → Assistant ID. |
fullName | string | Yes | – | Signed-in customer's full name. |
emailAddress | string | Yes | – | Signed-in customer's email address. |
mobilePhone | string | Yes | – | Signed-in customer's phone number in international format, e.g. +2348012345678. |
primaryColor | string | Yes | – | Brand color as hex (#RGB, #RRGGBB or #RRGGBBAA). Used for the chat button, header, the customer's messages and the buttons. |
firstCustomerMessage | string | No | – | A message sent on the customer's behalf as soon as initialize runs. See Send the customer's first message. |
launcher | boolean | No | true | Show the round chat button. Set false to open the chat only from your own button with FigoChat.open(). |
position | 'right' | 'left' | No | 'right' | Corner for the chat button and window. |
zIndex | number | No | 2147483000 | CSS z-index of the chat, if something on your page covers it. |
threadId | string | No | – | Resumes an earlier conversation. Use the value from FigoChat.getThreadId(). |
maxFiles | number | No | 5 | Most files per message. |
maxFileSizeMB | number | No | 10 | Largest file accepted. |
autoSendVoice | boolean | No | true | true sends the transcribed voice note right away. false puts the text in the input box so the customer can edit it first. |
timeoutMs | number | No | 120000 | Request timeout in milliseconds. |
baseUrl | string | No | https://api.figolabs.ai | API host. |
initialize throws a CONFIG error if a required value is empty or primaryColor isn't a hex color. It throws BROWSER_ONLY if it runs on a server (see the Next.js and Angular SSR notes below).
4. Add it to your framework#
The SDK is plain JavaScript, so in every framework you call initialize once when your app starts in the browser, and logout when the customer signs out.Angular#
Create a service and start it from your root component. With Angular SSR, only run it in the browser.// figo-chat.service.ts
import { Injectable, PLATFORM_ID, inject } from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import { FigoChat } from '@figoailabs/figochat-web';
@Injectable({ providedIn: 'root' })
export class FigoChatService {
private browser = isPlatformBrowser(inject(PLATFORM_ID));
start(user: { name: string; email: string; phone: string }) {
if (!this.browser) return;
FigoChat.initialize({
apiKey: 'YOUR_API_KEY',
assistantId: 'YOUR_ASSISTANT_ID',
fullName: user.name,
emailAddress: user.email,
mobilePhone: user.phone,
primaryColor: '#F97316',
});
}
open() {
if (this.browser) FigoChat.open();
}
stop() {
if (this.browser) FigoChat.logout();
}
}
// app.component.ts
import { Component, OnInit, inject } from '@angular/core';
import { FigoChatService } from './figo-chat.service';
@Component({
selector: 'app-root',
standalone: true,
template: `<button (click)="chat.open()">Need help?</button>`,
})
export class AppComponent implements OnInit {
chat = inject(FigoChatService);
ngOnInit() {
this.chat.start({ name: 'Ada Lovelace', email: 'ada@example.com', phone: '+2348012345678' });
}
}
Chat event listeners run outside Angular's change detection in zoneless apps. If a listener updates your component's state, update it through a signal, or wrap the update in NgZone.run.React#
import { useEffect } from 'react';
import { FigoChat } from '@figoailabs/figochat-web';
export function FigoChatWidget({ user }: { user: { name: string; email: string; phone: string } }) {
useEffect(() => {
FigoChat.initialize({
apiKey: import.meta.env.VITE_FIGO_API_KEY,
assistantId: import.meta.env.VITE_FIGO_ASSISTANT_ID,
fullName: user.name,
emailAddress: user.email,
mobilePhone: user.phone,
primaryColor: '#F97316',
});
return () => FigoChat.logout();
}, [user.email]);
return null;
}
Render <FigoChatWidget user={user} /> once, for example in your app layout after sign-in. In development, React's Strict Mode runs the effect twice. The cleanup removes the first chat, so you'll still see only one.Next.js#
The chat runs in the browser, so start it from a client component. It's safe to import in server components and during the build, but initialize must run in useEffect.// app/figo-chat.tsx
'use client';
import { useEffect } from 'react';
import { FigoChat } from '@figoailabs/figochat-web';
export default function FigoChatWidget() {
useEffect(() => {
FigoChat.initialize({
apiKey: process.env.NEXT_PUBLIC_FIGO_API_KEY!,
assistantId: process.env.NEXT_PUBLIC_FIGO_ASSISTANT_ID!,
fullName: 'Ada Lovelace',
emailAddress: 'ada@example.com',
mobilePhone: '+2348012345678',
primaryColor: '#F97316',
});
return () => FigoChat.logout();
}, []);
return null;
}
// app/layout.tsx
import FigoChatWidget from './figo-chat';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<FigoChatWidget />
</body>
</html>
);
}
Put the key and assistant ID in .env.local as NEXT_PUBLIC_FIGO_API_KEY and NEXT_PUBLIC_FIGO_ASSISTANT_ID.Plain HTML#
5. Send the customer's first message#
Pass firstCustomerMessage to send a message for the customer as soon as initialize runs. For example, use the question they typed in your site's own search or help box, then open the chat:FigoChat.initialize({ ...settings, firstCustomerMessage: searchBox.value });
FigoChat.open();
It's sent straight away, even before the chat is opened, exactly as if the customer had typed it.
The thread is kept, so the chat shows the welcome message, the customer's message and the reply, and the conversation continues from there.
While the reply is on its way, the chat shows the waiting message. The customer can't send another message until the reply arrives.
The messageSent and messageReceived events fire for it like any other message.
If it fails, it shows "Not sent. Tap to retry" in the chat.
6. Title, welcome message and waiting message#
These come from the chatbot's settings in the FigoChat admin, not from initialize. To change them, go to AI Chatbots, open your chatbot and click Edit. Changes show up the next time the page loads, with no site update needed.| Shown in the chat | Admin field | If it's empty |
|---|
| Header title | Persona (e.g. "Zoe"), otherwise Name | Chat |
| First bubble, before the customer writes | Welcome Message. HTML is shown as formatted text. | No welcome bubble |
| Left-hand bubble while a reply is on its way | Choose a Waiting Message | Animated dots |
If they can't be loaded, for example while offline, the chat still works with the defaults in the last column.
7. Open, close and other calls#
| Call | Description |
|---|
FigoChat.open() | Opens the chat window. |
FigoChat.close() | Closes the chat window. The chat button stays. |
FigoChat.toggle() | Opens the chat if it's closed, closes it if it's open. |
FigoChat.isOpen() | Whether the chat window is open. |
FigoChat.getThreadId() | Current thread ID, or undefined before the first reply. Save it to resume later with initialize({ threadId }). |
FigoChat.resetConversation() | Clears the chat window. The next message starts a new conversation. |
FigoChat.logout() | Removes the chat from the page and clears the settings, e.g. when the customer signs out. |
FigoChat.isInitialized() | Whether initialize has been called. |
FigoChat.getAssistantInfo() | The chatbot's assistantName, persona, waitingMessage and introMessage, or undefined until they've loaded. |
FigoChat.getClient() | The API client, for building your own chat UI: sendMessage, transcribe, uploadFiles, getAssistant. |
htmlToText(html) | A reply as plain text: tags removed, line breaks, • bullets and 1. numbers kept. |
htmlToRuns(html) | A reply as styled runs (text, bold, italic, underline, link), for showing it as formatted text in your own UI. |
friendlyMessage(error, context) | The customer-facing text for an error, as the chat shows it. context is chat, voice, recording or upload. |
8. Events#
Listen for chat events to log them, run analytics or update your page:const sent = FigoChat.addListener('messageSent', (text) => analytics.track('chat_message', { text }));
const received = FigoChat.addListener('messageReceived', (text) => console.log('Assistant:', text));
const opened = FigoChat.addListener('open', () => analytics.track('chat_opened'));
// later
sent.remove();
received.remove();
opened.remove();
| Event | When | Text |
|---|
messageSent | The API accepted the customer's message | What the customer sent |
messageReceived | An assistant reply or live agent message arrived | The reply as plain text (HTML removed) |
open | The chat window opened | Empty |
close | The chat window closed | Empty |
Listeners can be added before initialize and stay registered after logout. An error thrown in your listener never affects the chat.
9. What the chat does#
Text: type and press Enter to send. Shift+Enter adds a new line.
Formatted replies: assistant replies arrive as HTML and are shown as formatted text: bold, italics, headings, bullet and numbered lists, line breaks and links that open in a new tab. The chat writes replies as text, never as HTML, so a reply can't run scripts on your page. What customers type is always shown as typed.
Waiting message: while a reply is on its way, the chatbot's waiting message shows on the left.
Voice: customers click the microphone, speak, then click stop. The chat shows "Processing your voice message…" and then sends the text. Voice notes need HTTPS (or localhost) and microphone permission. The mic button is hidden in browsers that can't record.
Files: the paperclip uploads one or more files straight away. Images are read with OCR. When the customer sends, the files go with the message.
Live agent: when the conversation is handed to a human agent (Tawk.to, Zoho SalesIQ or FreshChat), the agent's replies appear in the same chat.
Errors: customers see plain-language messages such as "Chat isn't available right now. Please try again later." Technical details are never shown.
Phones: on small screens the chat opens full screen and stays above the on-screen keyboard.
Keyboard and screen readers: Escape closes the chat, every button has a label, and new messages are announced.
New conversation: the refresh button in the header starts a new thread.
Footer: a small "Powered by Figo AI Labs" line links to figolabs.ai.
10. Errors#
code | Meaning | What to do |
|---|
CONFIG | initialize is missing a required value, or primaryColor isn't hex. | Fix the options. |
BROWSER_ONLY | initialize ran on a server (SSR). | Call it in useEffect, ngOnInit with isPlatformBrowser, or another browser-only hook. |
NOT_INITIALIZED | A call was made before initialize. | Call initialize first. |
401 | Invalid or expired API key, or under 0.02 credits. | Check the key and the credit balance. |
49 | The company's plan doesn't include this API. | Upgrade the plan. |
TIMEOUT, NETWORK | No response, or no connection. | Retry. |
If the chat shows "You seem to be offline" on your site but works elsewhere, and the browser console shows a CORS error, your website's address isn't on FigoChat's list of allowed sites. Contact Figo AI Labs with the exact address, such as https://shop.example.com.Calls on FigoChat.getClient() throw FigoChatError with these codes. Inside the chat window, customers only see the friendly text.
11. Content Security Policy#
If your site sets a Content-Security-Policy, allow the API, the live agent connection and uploaded images:connect-src https://api.figolabs.ai wss://*.pusher.com https://*.pusher.com;
img-src https: blob:;
If you load the SDK from the CDN, also allow https://cdn.jsdelivr.net in script-src. Modified at 2026-11-20 14:18:29