Events
Public namespaced events emitted by the Customer Agent SDK.
Subscribe
on<TEventName extends CustomerAgentEventName>(
eventName: TEventName,
handler: (event: CustomerAgentEventMap[TEventName]) => void
): () => voidThe return value unsubscribes the handler.
Base Payload
Every event includes these fields.
| Field | Type | Meaning |
|---|---|---|
type | CustomerAgentEventName | Event name. |
appId | string | Customer Agent app id. |
widgetId | string | Runtime instance id. |
timestamp | string | ISO timestamp. |
Conversation Payload
Conversation and message events include conversation metadata when available.
| Field | Type | Meaning |
|---|---|---|
conversationId | string | Conversation identifier. |
conversationType | "support" | "interview" | string | Conversation product surface. |
entryId | string | Conversation entry id. |
supportConversationId | string | Support conversation id. |
interviewSessionId | string | Interview session id. |
Event Names
CUSTOMER_AGENT_EVENTS exposes these stable string values.
| Event | Additional payload | Effect |
|---|---|---|
widget.ready | None | Messenger UI is ready. |
widget.opened | None | Messenger opened. |
widget.closed | None | Messenger closed. |
widget.expanded | None | Messenger expanded. |
widget.collapsed | None | Messenger collapsed. |
conversation.created | Conversation payload | A support or interview conversation was created. |
transcript.downloaded | Conversation type, messageCount, optional conversation payload | A support or interview transcript was downloaded. |
support.state_changed | support: CustomerAgentSupportState | Support state changed. |
support.handoff_requested | Optional conversation payload | Human handoff was requested. |
support.feedback_submitted | Optional conversation payload, optional messageId | Message feedback was submitted. |
support.bug_reported | Optional conversation payload | Bug report was submitted. |
interview.state_changed | interview: CustomerAgentInterviewState | Interview state changed. |
interview.available | Available interview state fields | An interview invitation is available. |
interview.invitation_shown | campaignId, entryId, invitationId | An interview invitation was shown. |
interview.invitation_later | campaignId, entryId, invitationId | The invitation was deferred. |
interview.invitation_closed | campaignId, entryId, invitationId | The invitation was closed. |
interview.session_started | Conversation payload | An interview session started. |
interview.session_completed | Conversation payload, optional status | An interview session completed. |
interview.reward_updated | Optional conversation payload, optional reward | Interview reward data changed. |
message.sent | Optional conversation payload, messageId, role | User or assistant message submitted. |
message.send_failed | Optional conversation payload, optional messageId, role | Message request failed before completion. |
message.started | Conversation payload, optional messageId, role | Message response started. |
message.completed | Conversation payload, messageId, role, optional assistantAuthor | Message response completed. |
message.failed | Optional conversation payload, optional messageId, role | Message response failed. |
message.retry | Optional conversation payload, optional messageId, role | Message retry requested. |
error | message | SDK error reported. |
role is "assistant" or "user". assistantAuthor, when present, is "llm" or "human".
transcript.downloaded always includes conversationType, which is "support" for support
transcripts and "interview" for interview transcripts.
Handoff, feedback, bug report, and retry are public event names and are emitted only when the
matching Messenger behavior exists. The declared message payload type keeps role as
"assistant" | "user"; current response lifecycle events are emitted for assistant responses.
Event Types
| Type | Shape |
|---|---|
CustomerAgentEventName | Union of public event names. |
CustomerAgentEventMap | Map from event name to payload type. |