Widget
Events API
The Talki widget emits lifecycle events you can hook into via callbacks in window.TalkiConfig. Use them to sync UI state, fire analytics events, or trigger actions in your app.
All events
javascript
window.TalkiConfig = {
orgId: 'YOUR_ORG_ID',
apiKey: 'YOUR_API_KEY',
// Called when the widget chat panel opens
onOpen: () => {
console.log('Widget opened');
analytics.track('support_widget_opened');
},
// Called when the widget panel closes (button visible again)
onClose: () => {
console.log('Widget closed');
},
// Called each time the customer sends a message
onMessage: (message) => {
console.log('Customer sent:', message.text);
analytics.track('support_message_sent', { text: message.text });
},
// Called once after the widget script loads and is ready
onReady: () => {
console.log('Talki widget is ready');
// Safe to call window.Talki.open() from here
},
// Called when a new agent reply arrives
onAgentMessage: (message) => {
console.log('Agent replied:', message.text, 'from', message.agentName);
},
};| Event | Signature | When fired |
|---|---|---|
| onOpen | () => void | User clicks the launcher and the chat panel opens |
| onClose | () => void | User closes the chat panel (X button or click-away) |
| onMessage | (message: Message) => void | Customer submits a message |
| onAgentMessage | (message: AgentMessage) => void | An agent or AI sends a reply |
| onReady | () => void | Widget script finishes loading and is ready to use |
Message payload (onMessage)
The onMessage callback receives a Message object with the following fields:
| Name | Type | Description |
|---|---|---|
| text | string | Plain text content of the message. |
| ticketId | string | ID of the ticket this message belongs to. |
| createdAt | string | ISO 8601 timestamp of the message. |
Agent message payload (onAgentMessage)
The onAgentMessage callback receives an AgentMessage object:
| Name | Type | Description |
|---|---|---|
| text | string | Plain text content of the agent reply. |
| ticketId | string | ID of the ticket this reply belongs to. |
| agentName | string | Display name of the agent who replied. |
| createdAt | string | ISO 8601 timestamp of the reply. |
Analytics integration example
A common pattern is to fire analytics events alongside widget events to track support engagement in tools like PostHog, Mixpanel, or Amplitude.
javascript
// Example: PostHog analytics integration
window.TalkiConfig = {
orgId: 'YOUR_ORG_ID',
apiKey: 'YOUR_API_KEY',
onOpen: () => posthog.capture('support_opened'),
onMessage: (msg) => posthog.capture('support_message_sent', {
length: msg.text.length,
ticket_id: msg.ticketId,
}),
onClose: () => posthog.capture('support_closed'),
};✦Event order
onReady fires before any user interaction. If you want to call window.Talki.open() immediately on page load (e.g., for a support-only page), do it inside onReady.