Chat SDK Reference

Complete API reference for the @plucky-ai/chat-sdk package - the client-side SDK for embedding the Plucky chat widget in your application.

Installation

npm install @plucky-ai/chat-sdk
# or
yarn add @plucky-ai/chat-sdk
# or
pnpm add @plucky-ai/chat-sdk

Initialization

Plucky(options)

Initializes and mounts the Plucky chat widget on your page.

import { Plucky } from '@plucky-ai/chat-sdk'

Plucky({
  appId: 'your-app-id',
  baseUrl: 'https://widget.plucky.ai',
  user: {
    id: 'user-123',
    name: 'John Doe',
    email: '[email protected]',
  },
})

Options

Property	Type	Required	Description
appId	string	Yes	Your app ID from the Plucky platform
baseUrl	string	Yes	The widget server URL (typically https://widget.plucky.ai)
user	object	No	User identification object
systemTools	object	No	Configuration for built-in system tools
autoOpen	boolean	No	Whether to auto-open the widget when it loads. Defaults to true
triggerButton	boolean	No	Show a floating trigger button in the bottom-right corner. Defaults to false

User Object

Property	Type	Required	Description
id	string	Yes	Unique identifier for the user
name	string	No	Display name
email	string	No	User's email address
createdAt	string	No	ISO 8601 timestamp of when the user was created
metadata	Record<string, any>	No	Custom key-value data for the user

System Tools

Property	Type	Default	Description
readPage	boolean	false	Enable the built-in page reading capability

---

Widget Control

open()

Opens the chat widget.

import { open } from '@plucky-ai/chat-sdk'

open()

close()

Closes the chat widget.

import { close } from '@plucky-ai/chat-sdk'

close()

toggle()

Toggles the chat widget open/closed state.

import { toggle } from '@plucky-ai/chat-sdk'

// Toggle on button click
document.getElementById('chat-button').addEventListener('click', toggle)

setWidth(px)

Sets the width of the chat widget in pixels.

import { setWidth } from '@plucky-ai/chat-sdk'

setWidth(400) // Set widget width to 400px

Parameter	Type	Description
px	number	Width in pixels

setFullscreen(fullscreen)

Enables or disables fullscreen mode for the widget.

import { setFullscreen } from '@plucky-ai/chat-sdk'

setFullscreen(true) // Enter fullscreen
setFullscreen(false) // Exit fullscreen

Parameter	Type	Description
fullscreen	boolean	Whether to enable fullscreen mode

showTriggerButton()

Shows the floating trigger button. If the trigger button was not enabled during initialization, this will create and mount it.

import { showTriggerButton } from '@plucky-ai/chat-sdk'

showTriggerButton()

hideTriggerButton()

Hides the floating trigger button without removing it from the DOM.

import { hideTriggerButton } from '@plucky-ai/chat-sdk'

hideTriggerButton()

unmount()

Removes the chat widget from the DOM entirely.

import { unmount } from '@plucky-ai/chat-sdk'

unmount()

---

Messaging

sendMessage(args)

Programmatically sends a message to the chat.

import { sendMessage } from '@plucky-ai/chat-sdk'

sendMessage({
  content: 'Hello, I need help with my order',
  createChat: true, // Optional: create a new chat if none exists
})

Parameter	Type	Required	Description
content	string	Yes	The message content to send
createChat	boolean	No	Whether to create a new chat if one doesn't exist

setInput(args)

Pre-fills the chat input field without sending.

import { setInput } from '@plucky-ai/chat-sdk'

setInput({
  content: 'I want to know about...',
})

Parameter	Type	Required	Description
content	string	Yes	The text to pre-fill in the input

---

User Management

updateSettings(settings)

Updates user information after the widget has been initialized.

import { updateSettings } from '@plucky-ai/chat-sdk'

// Update user after login
updateSettings({
  user: {
    id: 'user-456',
    name: 'Jane Smith',
    email: '[email protected]',
    metadata: {
      plan: 'premium',
      company: 'Acme Inc',
    },
  },
})

Parameter	Type	Description
user	object	Updated user object (same structure as initialization)

---

Tool Management

addTools(tools)

Registers one or more tools that the AI can call.

import { addTools } from '@plucky-ai/chat-sdk'
import { z } from 'zod'

addTools([
  {
    name: 'get_order_status',
    description: 'Get the status of a customer order',
    inputSchema: z.object({
      orderId: z.string().describe('The order ID to look up'),
    }),
    defaultLoadingText: 'Looking up order...',
    defaultSuccessText: 'Order found.',
    cb: async (input) => {
      const order = await fetchOrder(input.orderId)
      return `Order ${input.orderId}: ${order.status}`
    },
  },
])

For comprehensive documentation on tool configuration, see the Tool Calls guide.

removeTools(names)

Unregisters tools by their names.

import { removeTools } from '@plucky-ai/chat-sdk'

removeTools(['get_order_status', 'cancel_order'])

Parameter	Type	Description
names	string[]	Array of tool names to remove

---

Events

addEventListener(event, listener)

Subscribes to widget events.

import { addEventListener } from '@plucky-ai/chat-sdk'

addEventListener('message', (payload) => {
  console.log('New message:', payload)
})

Parameter	Type	Description
event	string	The event name to listen for
listener	(payload: any) => void	Callback function

removeEventListener(event, listener)

Unsubscribes from widget events.

import { removeEventListener } from '@plucky-ai/chat-sdk'

const handler = (payload) => console.log(payload)

// Subscribe
addEventListener('message', handler)

// Later, unsubscribe
removeEventListener('message', handler)

isReady()

Checks if the widget has finished initializing.

import { isReady } from '@plucky-ai/chat-sdk'

if (isReady()) {
  // Widget is ready to use
  sendMessage({ content: 'Hello!' })
}

Returns boolean - true if the widget is initialized and ready.

---

TypeScript

The SDK is written in TypeScript and exports all types:

import type { ToolConfig, PluckySettingsParams } from '@plucky-ai/chat-sdk'

Key Types

// Tool configuration
interface ToolConfig {
  name: string
  description: string
  inputSchema?: ZodObject | Record<string, unknown>
  defaultLoadingText?: string | null
  defaultSuccessText?: string | null
  cb?: (input: any) => Promise<ToolCallbackResult> | ToolCallbackResult
}

// Tool callback return type
type ToolCallbackResult =
  | string
  | {
      content: string
      successText?: string
    }

// Initialization options
type PluckySettingsParams = {
  baseUrl: string
  appId: string
  user?: {
    id: string
    name?: string
    email?: string
    createdAt?: string
    metadata?: Record<string, any>
  }
  systemTools?: {
    readPage?: boolean
  }
  autoOpen?: boolean
  triggerButton?: boolean
}