Skip to Content

Events & Callbacks

Control the widget programmatically and pass conversation context. Load the script once and use the Agent ID and widget API key from Deploy.

The loader makes init, open, close, toggle, setUser, and setCustomFields available after it executes, queuing these controls while the widget bundle loads. reset is available after the full widget initializes. This page documents methods; a general event-subscription API is not exposed.

Browser-provided user fields are not verified identity. Do not use them as authorization for private account information.

Initialization Methods

There are three ways to configure the widget:

1. Global Config Object

Set configuration before the script loads:

window.loopReplyConfig = {
  agentId: 'your-agent-id',
  apiKey: 'your-widget-api-key',
  user: {
    id: 'user-123',
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1234567890'
  },
  customFields: {
    plan: 'premium',
    company: 'Acme Inc'
  }
}

2. Data Attributes

Configure via script tag attributes:

<script
  src="https://widget.loopreply.com/loader.js"
  data-agent-id="your-agent-id"
  data-api-key="your-widget-api-key"
  data-user-name="John Doe"
  data-user-email="john@example.com"
  data-custom='{"plan":"premium"}'
  async
></script>

3. JavaScript API

Initialize programmatically:

LoopReply.init({
  agentId: 'your-agent-id',
  apiKey: 'your-widget-api-key',
  user: { name: 'John', email: 'john@example.com' },
  customFields: { plan: 'premium' }
})

Configuration Options

OptionTypeDescription
agentIdstringRequired. Your Agent’s unique ID
apiKeystringRequired for the public widget. Copy the widget key from Deploy
apiUrlstringOptional. Custom API endpoint URL
previewbooleanReserved for the dashboard preview; keep it off for public installations
userobjectUser identification data
customFieldsobjectCustom data to attach to conversations

User Object

{
  id?: string      // Your internal user ID
  name?: string    // Display name
  email?: string   // Email address
  phone?: string   // Phone number
}

Methods

init(config)

Initialize the widget with configuration:

LoopReply.init({
  agentId: 'your-agent-id',
  apiKey: 'your-widget-api-key',
  user: { name: 'John', email: 'john@example.com' }
})

open()

Open the chat widget:

LoopReply.open()

close()

Close the chat widget:

LoopReply.close()

toggle()

Toggle the widget open/closed:

LoopReply.toggle()

setUser(user)

Update user information:

LoopReply.setUser({
  id: 'user-123',
  name: 'John Doe',
  email: 'john@example.com',
  phone: '+1234567890'
})

setCustomFields(fields)

Update custom fields:

LoopReply.setCustomFields({
  plan: 'enterprise',
  company: 'Acme Inc',
  accountId: 'acc_123'
})

reset()

After the full widget has initialized, reset its local conversation state:

window.LoopReply?.reset?.()

Use Cases

Custom Open Triggers

Open the widget from custom buttons:

<button onclick="LoopReply.open()">
  Chat with us
</button>
 
<a href="#" onclick="LoopReply.open(); return false;">
  Need help?
</a>

Pre-fill User Data

Identify logged-in users:

// After widget script loads
const user = getCurrentUser() // Your auth system
 
if (user) {
  LoopReply.setUser({
    id: user.id,
    name: user.fullName,
    email: user.email
  })
}

Track Custom Data

Attach context to conversations:

// On page load
LoopReply.setCustomFields({
  page: document.title,
  url: window.location.href,
  referrer: document.referrer
})
 
// When cart updates
function onCartUpdate(cart) {
  LoopReply.setCustomFields({
    cartItems: cart.items.length,
    cartTotal: cart.total
  })
}

Reset on Logout

Clear widget state when user logs out:

function handleLogout() {
  window.LoopReply?.reset?.()
  // ... rest of logout logic
}

TypeScript Support

Type definitions for the widget API:

interface LoopReplyUser {
  id?: string
  name?: string
  email?: string
  phone?: string
}
 
interface LoopReplyConfig {
  agentId: string
  apiKey: string
  apiUrl?: string
  preview?: boolean
  user?: LoopReplyUser
  customFields?: Record<string, string | number | boolean>
}
 
interface LoopReply {
  init(config: LoopReplyConfig): void
  open(): void
  close(): void
  toggle(): void
  setUser(user: LoopReplyUser): void
  setCustomFields(fields: Record<string, string | number | boolean>): void
  reset(): void
}
 
declare global {
  interface Window {
    LoopReply?: LoopReply
    loopReplyConfig?: LoopReplyConfig
  }
}

Last updated on