Skip to main content

Webchat JS SDK v2

Webchat JS SDK is a Javascript library that helps you integrate Filum chat functionality directly into your website.

Installation​

Copy this snippet and put it within the body tag of your website:

<script 
  type="text/javascript" 
  src="https://assets.filum.ai/chat/filum_chat_latest.js">
</script>
caution

If you are using Wordpress with some caching mechanism, please refrain from caching our script. It is so that we can actively improve and provide fixes when necessary. Our script is already served from a server closest to you.

Usage​

You can access the SDK via the window.filumChat object. The SDK has the following methods:

initialize(config)​

Attach the chat widget to your page with your organization's configuration. This method must be called before using any other methods.

window.filumChat.initialize({
  organizationId: 'your-organization-id',
  installedSourceId: 123
})

The config object accepts the following properties:

  • organizationId (required): Your organization's unique identifier
  • installedSourceId (required): The source identifier for this chat installation
  • hideLauncherButton (optional): Show/hide the launcher button of the chat. Default: false
  • zIndex (optional): The zIndex of the chat. Default: 2147483640
  • openAfterAttached (optional): If true, the chat will automatically open when the initialization step is completed. Default: false.
  • showDebugFrame (optional): Default: false. Enabling this option will show a red frame of the chat client. You should never use this option in your production environment.

Example: Install the webchat in a Next.js (App Router) app​

Update your layout.tsx (or layout.jsx) file to add our script:

// app/layout.tsx
import Script from 'next/script'

export default function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}

        {/* Filum Chat script (loaded once for the whole app) */}
        <Script
          src="https://assets.filum.ai/chat/filum_chat_latest.js"
          strategy="afterInteractive"
          onLoad={() => {
            if (window.filumChat) {
              window.filumChat.initialize({
                organizationId: 'your-organization-id',
                installedSourceId: 123
              })
            }
          }}
        />
      </body>
    </html>
  )
}

Example: Install the webchat in a React app​

import { useEffect } from 'react'

export function FilumWebchat() {
  useEffect(() => {
    if (document.getElementById('filum-chat-script')) return

    const script = document.createElement('script')
    script.id = 'filum-chat-script'
    script.src = 'https://assets.filum.ai/chat/filum_chat_latest.js'
    script.async = true

    script.onload = () => {
      if (window.filumChat) {
        window.filumChat.initialize()
      } else {
        console.warn('filumChat not available')
      }
    }

    document.body.appendChild(script)

    return () => {
      // Cleanup when component unmounts
      script.remove()
      // If the chat library attaches a global, clear it
      if (window.filumChat) {
        try {
          window.filumChat.destroy?.() // if destroy method exists
        } catch (err) {
          console.warn('Failed to clean up filumChat', err)
        }
        delete (window as any).filumChat
      }
    }
  }, [])

  return <></>
}

Example: Open chat immediately after initialize​

Since initialize() is an asynchronous function, if you want to open the chat immediately afterward, you can use the following snippet:

window.filumChat.initialize({
  organizationId: 'your-organization-id',
  installedSourceId: 123,
  openAfterAttached: true
})

Example: Hiding the launcher button​

window.filumChat.initialize({
  organizationId: 'your-organization-id',
  installedSourceId: 123,
  hideLauncherButton: true
})

Example: Setting up locales​

Webchat currently supports 2 languages: English and Vietnamese. By default, it follows the language set by your web browser and fallback to English if the browser locale is not supported. In case you want the chat to only fixate on one locale, you can override the default using this snippet:

window.filumChat.initialize({
  organizationId: 'your-organization-id',
  installedSourceId: 123,
  locale: 'en' // or "vi". More languages to be added
})

Example: Customizing the z-index of the chat​

In some cases you might have to update the zIndex of that chat so that it doesn't stay on top of your, say, modals. If the zIndex of your modal or dialog is 9999, you can set a lower value for our chat's zIndex:

window.filumChat.initialize({
  organizationId: 'your-organization-id',
  installedSourceId: 123,
  zIndex: 9998
})

Example: Customizing the chat position​

By default, the chat SDK stays fixed in the bottom-right corner of the page, with a 10px offset from the bottom and right edges. You can tweak the offset value using the following config:

window.filumChat.initialize({
  organizationId: 'your-organization-id',
  installedSourceId: 123,

  // Change the offset value to 25 pixels
  positionRight: 25, // or "10%" or "5rem"
  positionBottom: 25 // or "10%" or "5rem"
})

Example: Callback whenever webchat is shown (show()) or hidden (hide())​

window.filumChat.initialize({
  organizationId: 'your-organization-id',
  installedSourceId: 123,

  onOpenChange: (open: boolean) => {
    console.log(`Webchat is opened: ${open}`)
  }
})
TypeScript References
interface Config {
  organizationId: string
  installedSourceId: number
  hideLauncherButton?: boolean
  showDebugFrame?: boolean
  zIndex?: number
  positionRight?: string | number
  positionBottom?: string | number
  openAfterAttached?: boolean
  onOpenChange?: (open: boolean) => void
}

enum MessageSenderType {
  Agent = 'agent',
  System = 'system',
  AI = 'ai',
  Assistant = 'assistant'
}

enum AttachmentType {
  File = 'file',
  Image = 'image',
  Video = 'video'
}

export interface Message {
  _id: string
  originalId?: string
  text: string | null
  status?: Status
  createdAt: string
  senderType: MessageSenderType
  attachments?: Attachment[]
  changeLog?: Record<string, any>
  conversationId?: string
  replyToMessageId?: string
  failedReason?: string
  user?: Customer // refer to the Customer interface at the end of this guide
}

show()​

Once the chat sdk has been attached to the page, you can open the chat frame using the open method.

window.filumChat.show()

Example: Use your own button to open the chat widget​

<button onclick="window.filumChat.show()">Open chat</button>

<!-- OR -->

<script>
  document.getElementById('open-chat-button').addEventListener('click', () => {
    window.filumChat.show()
  })
</script>

hide()​

Similar to show, hide can be called to collapse the chat, showing only the launcher button.

window.filumChat.hide()

Example: Use your own button to hide the chat widget​

<button onclick="window.filumChat.hide()">Hide chat</button>

<!-- OR -->

<script>
  document.getElementById('hide-chat-button').addEventListener('click', () => {
    window.filumChat.hide()
  })
</script>

destroy()​

destroy() should only be called when you want to remove the chat completely from the page. After the chat has been destroyed, your customers will not receive any further messages from you (the business)

window.filumChat.destroy()

Example: Full Implementation​

Here's a complete example of how to implement the Chat SDK on your website:

<!DOCTYPE html>
<html>
  <head>
    <title>My Website with Filum Chat</title>
  </head>
  <body>
    <!-- Your website content -->

    <!-- Filum Chat SDK -->
    <script
      type="text/javascript"
      src="https://assets.filum.ai/chat/filum_chat_latest.js"
    ></script>

    <script>
      window.filumChat.initialize({
        organizationId: 'your-organization-id',
        installedSourceId: 123
      })
    </script>
  </body>
</html>

Configure your webchat appearance​

Please go to your Webchat Settings page.

TypeScript References​

interface Customer {
  id?: string
  name?: string
  email?: string
  avatar?: string
  phone?: string
  filumUserId?: string
}

interface SessionPayload {
  organizationId: string
  installedSourceId: number
  user: Customer
}

interface InfoInput {
  id: string
  title: string
  isRequired?: boolean
  type?: string
  _id?: string
}

interface WebchatAppearance {
  brandColor?: string
  agentAvatar?: string
  widgetPosition?: string
  widgetLogo?: string
  widgetDescription?: string
  widgetName?: string
  widgetSize?: {
    width?: string | number
    height?: string | number
  }
  parentElement?: HTMLElement | null
  launcherSize: number
  launcherLabel: string
  fontUrls?: {
    semiBold?: string
    normal?: string
  }
}

interface Content {
  welcomeMessage?: string
  suggestedMessages?: string[]
  infoCollection?: {
    enabled?: boolean
    message?: string
    inputs?: InfoInput[]
  }
  backButtonLabel?: string
  startButtonLabel?: string
  showLauncherMessages?: boolean
}

interface ChatConfig {
  appearance: WebchatAppearance
  content?: Content
  outsideWorkingHoursContent?: Content
  isPreview?: boolean
  session?: Partial<SessionPayload>
  schedule?: ZippedSchedule[] | null
  allSchedule?: boolean
  showOutsideWorkingHours?: boolean
}

declare global {
  interface Window {
    filumChat: {
      initialize: (config: ChatConfig) => Promise<void> // asynchronous
      destroy: () => void
      show: () => void
      hide: () => void
    }
  }
}

Migration from Chat SDK v1​

Unfortunately, the Chat SDK v2 is a complete rewrite and provides no backward-compatibility. Should you choose to upgrade to v2, you can simply remove the v1 import script on your website:

  • maximize() -> No longer required
  • minimized() -> No longer required
  • onMessage() has been removed. We are redesigning this feature with better ergonomics & customizability.

Support​

Please contact the Filum Engineering Team if you encounter any issues integrating the SDK.