JavaScript API reference

if (posthog.conversations.isAvailable()) {
  // Conversations API is ready to use
}

// Send a message (creates ticket if none exists)
const response = await posthog.conversations.sendMessage('Hello, I need help!')

// Send with user identification
const response = await posthog.conversations.sendMessage(
  'Hello, I need help!',
  { 
    name: 'John Doe', 
    email: 'john@example.com' 
  }
)

// Force start a new conversation (new ticket)
const response = await posthog.conversations.sendMessage(
  'Starting a new conversation',
  undefined,  // userTraits
  true        // newTicket
)

interface SendMessageResponse {
  ticket_id: string      // ID of the ticket
  message_id: string     // ID of the created message
  ticket_status: string  // 'new' | 'open' | 'pending' | 'on_hold' | 'resolved'
  created_at: string     // ISO timestamp
  unread_count: number   // Unread messages from team (0 after sending)
}

// Get messages for the current active ticket
const response = await posthog.conversations.getMessages()

// Get messages for a specific ticket
const response = await posthog.conversations.getMessages('ticket-uuid')

// Get messages after a specific timestamp (for pagination)
const response = await posthog.conversations.getMessages(
  'ticket-uuid',
  '2024-01-15T10:30:00Z'
)

interface GetMessagesResponse {
  ticket_id: string
  ticket_status: string
  messages: Message[]
  has_more: boolean      // Whether more messages exist
  unread_count: number   // Unread messages from team
}

interface Message {
  id: string
  content: string
  author_type: 'customer' | 'AI' | 'human'
  author_name?: string
  created_at: string     // ISO timestamp
  is_private: boolean    // Internal notes (not shown to customer)
}

// Mark messages as read for current ticket
await posthog.conversations.markAsRead()

// Mark messages as read for a specific ticket
await posthog.conversations.markAsRead('ticket-uuid')

interface MarkAsReadResponse {
  success: boolean
  unread_count: number   // Should be 0 after marking as read
}

// Get all tickets
const response = await posthog.conversations.getTickets()

// Get tickets with filters
const response = await posthog.conversations.getTickets({
  status: 'open',
  limit: 10,
  offset: 0
})

interface GetTicketsOptions {
  status?: string   // Filter by status: 'new' | 'open' | 'pending' | 'on_hold' | 'resolved'
  limit?: number    // Number of tickets to return (default: 20)
  offset?: number   // Pagination offset (default: 0)
}

interface GetTicketsResponse {
  count: number      // Total count of tickets
  results: Ticket[]  // Array of tickets
}

interface Ticket {
  id: string
  status: string
  last_message?: string
  last_message_at?: string
  message_count: number
  created_at: string
  unread_count?: number
}

// Get the current active ticket ID (null if no conversation started)
const ticketId = posthog.conversations.getCurrentTicketId()

// Get the widget session ID (persistent browser identifier)
const sessionId = posthog.conversations.getWidgetSessionId()

// In PostHog settings: set widgetEnabled to false

// Your custom implementation
async function initCustomChat() {
  // Wait for conversations to be available
  const checkAvailable = setInterval(() => {
    if (posthog.conversations.isAvailable()) {
      clearInterval(checkAvailable)
      loadExistingMessages()
    }
  }, 100)
}

async function loadExistingMessages() {
  const ticketId = posthog.conversations.getCurrentTicketId()
  if (ticketId) {
    const response = await posthog.conversations.getMessages()
    renderMessages(response.messages)
  }
}

async function sendMessage(text, userEmail) {
  const response = await posthog.conversations.sendMessage(text, {
    email: userEmail
  })
  // Add optimistic UI update
  addMessageToUI({
    id: response.message_id,
    content: text,
    author_type: 'customer',
    created_at: response.created_at
  })
}

// Poll for new messages
setInterval(async () => {
  if (posthog.conversations.getCurrentTicketId()) {
    const response = await posthog.conversations.getMessages()
    updateMessagesUI(response.messages)
  }
}, 5000)

await posthog.conversations.requestRestoreLink('user@example.com')

const result = await posthog.conversations.restoreFromUrlToken()

interface RestoreResult {
  status: 'success'
  migrated_ticket_ids: string[]  // IDs of tickets migrated to this session
}

// Option 1: Check availability first
if (posthog.conversations.isAvailable()) {
  const response = await posthog.conversations.sendMessage('Hello')
}

// Option 2: Handle null response
const response = await posthog.conversations.sendMessage('Hello')
if (response) {
  console.log('Message sent:', response.message_id)
}

try {
  await posthog.conversations.sendMessage('Hello')
} catch (error) {
  if (error.message.includes('Too many requests')) {
    // Handle rate limiting - wait and retry
  }
}