Sync features: Lex streaming, transcript updates, and agent metrics

[saipreetham16]

Sync features: Lex streaming, transcript updates, and agent metrics

---

Overview

Adding support for Lex streaming responses, real-time transcript tracking, and agent-specific metrics.

Changes Summary

Customer-Facing Features

• Lex Streaming Support: Bot responses are now stitched from streaming chunks before being displayed
• Transcript Updates: New onTranscriptUpdated event provides real-time transcript state with message statuses
• Workflow Events: Added support for workflow cancellation events

Developer Features

• TypeScript Types: Added MessageProcessingStatus type definition
• Agent Metrics: Track connection errors for agent sessions (excludes 4xx client errors)
• Enhanced Metadata: Messages now include MessageCompleted, ChunkNumber, and MessageProcessingStatus fields

Commits Included

1. Add partial message stitching (93a3ea4)

   • Handles bot messages sent in chunks
   • Stitches partial messages before emitting to UI
   • Prevents flickering/incomplete messages in chat widget

2. Add transcriptUpdated event (e871068)

   • New chatSession.onTranscriptUpdated() callback
   • Provides full transcript state with message statuses
   • Auto-fetches 100 messages on connection
   • Tracks message lifecycle: SENDING → SENT → DELIVERED → READ

3. Add workflow cancelled event (a73ec52)

   • Adds workflowCanceled content type constant
   • Enables handling of workflow cancellation events from Connect flows

4. Support Lex streaming for transcriptUpdated (86ca9f6)

   • Fixes transcript tracking for partial/streaming messages
   • Tracks stitched messages instead of individual chunks
   • Adds MessageCompleted and ChunkNumber to TypeScript types

5. Add agent metrics (f2c5177)

   • Track AGENT_CREATE_PARTICIPANT_ERROR_RATE metric
   • Track AGENT_GET_CONNECTION_TOKEN_ERROR_RATE metric
   • Agent-session specific, doesn't affect customer sessions

6. Add MessageProcessingStatus TypeScript type (80b9daa)

   • Adds interface for message processing states: PROCESSING, FAILED, REJECTED
   • Improves TypeScript support for message metadata

7. Update default max results for transcript (5b94790)

   • Increases auto-fetch from 15 to 100 messages on connection
   • Improves initial transcript completeness

8. Exclude 4xx errors from agent error metric (91e963f)

   • Only tracks 5xx and network errors as service failures
   • 4xx errors are client errors, not service issues

Testing

Automated Tests

• All 279 unit tests passing
• No breaking changes to existing APIs

Manual Testing

• Partial message stitching verified with Lex bot
• Transcript updates fire correctly on all events
• Message metadata fields populated correctly
• No console errors in customer or agent sessions

Test Coverage

• Partial message stitching: PartialMessageUtil.spec.js
• Transcript updates: chatController.transcript.spec.js, internalTranscriptUtils.spec.js
• Agent metrics: connectionDetailsProvider.spec.js

Breaking Changes

None. All changes are backward compatible.

API Changes

New APIs

// New event subscription
chatSession.onTranscriptUpdated((event) => {
  console.log(event.data.transcript); // Array of messages with statuses
  console.log(event.data.previousTranscriptNextToken); // Pagination token
});

New TypeScript Types

interface MessageProcessingStatus {
  readonly PROCESSING: "PROCESSING";
  readonly FAILED: "FAILED";
  readonly REJECTED: "REJECTED";
}

interface MessageMetadata {
  MessageProcessingStatus?: MessageProcessingStatus[keyof MessageProcessingStatus];
  MessageCompleted?: boolean;
  ChunkNumber?: number;
}

New Constants

CONTENT_TYPE.workflowCanceled
AGENT_CREATE_PARTICIPANT_ERROR_RATE
AGENT_GET_CONNECTION_TOKEN_ERROR_RATE
MESSAGE_STATUS.SENDING | SENT | DELIVERED | READ | FAILED | UNKNOWN

---

Screen.Recording.2026-01-30.at.10.32.46.PM.mov

[xiajon]

can you check if this metric is suppose to only be for default CCP agents or it should include custom CCP as well?

[saipreetham16]

The AGENT_CREATE_PARTICIPANT_ERROR_RATE metric is to monitor agent sessions (both default CCP and custom CCP). logic:

• this._isAgentSession() - Filters for agent sessions (vs customer)
• !error?.statusCode?.toString().startsWith("4") - Excludes 4xx client errors
• Tracks server-side connectivity issues affecting agents

This is will monitoring agent connection health across all CCP implementations.

[xiajon]

can you add this event to the readme

[haomingli2020]

Changes LGTM, the only thing I noticed in the video is that the chat window doesn't scroll automatically to the bottom when the partial messages continue to come from lex, is that the desired behavior ? (for both internal package and this repo).

[saipreetham16]

Changes LGTM, the only thing I noticed in the video is that the chat window doesn't scroll automatically to the bottom when the partial messages continue to come from lex, is that the desired behavior ? (for both internal package and this repo).

This is expected for longer responses now, will create a backlog for this.