FigoAILabs API Documentation
    • Quickstart
    • Website Plugin
    • Mobile Plugin
    • Rate Limits & Pricing
    • FigoChat Web SDK
    • FigoChat Mobile SDK
    • Figo Snap and Pay SDK
    • APIs
      • Chat Assistant API
        POST
      • Image Assistant API
        POST
      • Text To Speech API
        POST
      • Speech To Text API
        POST
      • Guardrails API
        POST
      • CV Scoring API
        POST
      • Web Search API
        POST
      • Sentiment Analysis API
        POST
      • Message Context API
        POST
      • Image Analyzer API
        POST
      • Upload Files With OCR
        POST
      • Extract Bank Account From Image
        POST
      • Check Assistant Health
        GET
    • Schemas
      • Sample Schemas
        • Pet
        • Category
        • Tag
      • Schemas
        • ApiKeyRequest
        • Assignee
        • AssistantRequest
        • AssistantTrainingRequest
        • AssistantTrainingRequestByUrl
        • CVScoringRequest
        • Cf
        • Change
        • ChangePasswordRequest
        • ChangePlanRequest
        • ChatRequest
        • ChatUser
        • CompanyEntityCreateRequest
        • CompanyEntityUpdateRequest
        • CompanyPreferenceUpdateRequest
        • ConfirmPasswordRequest
        • Contact
        • CreateUserRequest
        • CustomFields
        • CustomerContact
        • DescAttachment
        • Entry
        • FAQ
        • FBEntry
        • FBMessage
        • FBMessaging
        • FBRecipient
        • FBSendMessage
        • FBSender
        • FacebookReceiveMessageRequest
        • FacebookSendMessageRequest
        • FacebookSetupRequest
        • GoogleSignInRequest
        • GuardrailForAssistantRequest
        • GuardrailRequest
        • HallucinationTrack
        • IGEntry
        • IGMessage
        • IGMessaging
        • IGRecipient
        • IGSendMessage
        • IGSender
        • ImageChatRequest
        • ImageDefaultChatRequest
        • InstagramReceiveMessageRequest
        • InstagramSendMessageRequest
        • InstagramSetupRequest
        • LLMPoolRequest
        • LLMRequest
        • LayoutDetails
        • Message
        • MessageRequest
        • MessageRequestForWebSearch
        • Metadata
        • Payload
        • Profile
        • RefreshTokenRequest
        • RemitaPersonalSignInRequest
        • RemitaSignInRequest
        • RequestOTPRequest
        • ResetPasswordRequest
        • SaveAssistantFAQByTextRequest
        • SaveAssistantFAQByUrlRequest
        • SaveAssistantFAQRequest
        • SaveToolingAgentMapRequest
        • SaveToolingAgentRequest
        • SentimentValidationRequest
        • SignInRequest
        • SignUpRequest
        • TWDirectMessageEvent
        • TWMessageCreate
        • TWMessageData
        • TWTarget
        • TeamsLoginRequest
        • Text
        • TextToSpeechRequest
        • TransactionInitializeRequest
        • TwitterReceiveMessageRequest
        • TwitterSendMessageRequest
        • TwitterSetupRequest
        • UpdateAssistantFAQRequest
        • UpdateUserRequest
        • ValidateOTPRequest
        • Value
        • VerifyEmailRequest
        • WhatsAppReceiveMessageRequest
        • WhatsAppSendMessageRequest
        • WhatsAppSetupRequest
        • ZohoCreateTicketRequest
        • ZohoReceiveMessageRequest
        • ZohoReplyTicketRequest
        • ZohoSetupRequest
      • AssistantHealthResponse
      • FileUploadResponse
      • BankAccountExtractRequest
      • RateLimitResponse
      • BankAccountExtractResult
      • RawFile
      • LLMImage
      • StandardResponse

    FigoChat Web SDK

    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 withAngular, React, Next.js (App Router and Pages Router), Vue, Svelte or plain JavaScript
    BrowsersCurrent Chrome, Edge, Firefox and Safari, on desktop and mobile
    SizeAbout 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#

    You need three things, all from the FigoChat admin at app.figolabs.ai:
    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.
    The chat's title, welcome message and waiting message come from the chatbot's settings in the admin. See Title, welcome message and waiting message.
    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#

    OptionTypeRequiredDefaultDescription
    apiKeystringYes–API key from API Keys in the FigoChat admin. Sent as Authorization: Bearer <apiKey>.
    assistantIdstringYes–AI Chatbots → your chatbot → Assistant ID.
    fullNamestringYes–Signed-in customer's full name.
    emailAddressstringYes–Signed-in customer's email address.
    mobilePhonestringYes–Signed-in customer's phone number in international format, e.g. +2348012345678.
    primaryColorstringYes–Brand color as hex (#RGB, #RRGGBB or #RRGGBBAA). Used for the chat button, header, the customer's messages and the buttons.
    firstCustomerMessagestringNo–A message sent on the customer's behalf as soon as initialize runs. See Send the customer's first message.
    launcherbooleanNotrueShow 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.
    zIndexnumberNo2147483000CSS z-index of the chat, if something on your page covers it.
    threadIdstringNo–Resumes an earlier conversation. Use the value from FigoChat.getThreadId().
    maxFilesnumberNo5Most files per message.
    maxFileSizeMBnumberNo10Largest file accepted.
    autoSendVoicebooleanNotruetrue sends the transcribed voice note right away. false puts the text in the input box so the customer can edit it first.
    timeoutMsnumberNo120000Request timeout in milliseconds.
    baseUrlstringNohttps://api.figolabs.aiAPI 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 chatAdmin fieldIf it's empty
    Header titlePersona (e.g. "Zoe"), otherwise NameChat
    First bubble, before the customer writesWelcome Message. HTML is shown as formatted text.No welcome bubble
    Left-hand bubble while a reply is on its wayChoose a Waiting MessageAnimated 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#

    CallDescription
    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();
    EventWhenText
    messageSentThe API accepted the customer's messageWhat the customer sent
    messageReceivedAn assistant reply or live agent message arrivedThe reply as plain text (HTML removed)
    openThe chat window openedEmpty
    closeThe chat window closedEmpty
    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#

    codeMeaningWhat to do
    CONFIGinitialize is missing a required value, or primaryColor isn't hex.Fix the options.
    BROWSER_ONLYinitialize ran on a server (SSR).Call it in useEffect, ngOnInit with isPlatformBrowser, or another browser-only hook.
    NOT_INITIALIZEDA call was made before initialize.Call initialize first.
    401Invalid or expired API key, or under 0.02 credits.Check the key and the credit balance.
    49The company's plan doesn't include this API.Upgrade the plan.
    TIMEOUT, NETWORKNo 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
    Previous
    Rate Limits & Pricing
    Next
    FigoChat Mobile SDK
    Built with