pre:stream:delta

Triggered before each streaming delta chunk is processed and rendered in the chat. This event is fired only during streaming responses when the agent sends partial content incrementally. Use this event to inspect, modify, or suppress streaming content before it appears in the chat UI.

This event is only triggered when you use streaming responses. Non-streaming responses do not fire this event.

Event properties

string

required

Always 'pre:stream:delta'.

string

required

Unique identifier for the message being streamed.

string

required

Unique identifier for the conversation thread.

string

required

Unique identifier for the current run.

object

required

The streaming delta chunk containing partial response content.

string

Role of the message sender, for example, 'assistant'.

array

Array of content items in the delta chunk. Contains only the incremental content for the current chunk, not the complete message. To suppress delta rendering, set this to an empty array ([]). The complete message is still rendered with pre:receive and receive events.

string

Unique identifier for the content item.

string

Type of the response item, for example, 'text'.

string

Text content of the delta item.

Examples

The following example modifies an streaming content:

instance.on('pre:stream:delta', (event, instance) => {
    console.log('Streaming delta received:', event);
    console.log('Message ID:', event.messageId);
    console.log('Thread ID:', event.threadId);
    
    // Modify streaming text before it's rendered
    event?.delta?.content?.forEach((contentItem) => {
        if (contentItem.response_type === 'text' && contentItem.text) {
            // Convert streaming text to uppercase
            contentItem.text = contentItem.text.toUpperCase();
            
            // Filter out specific words or phrases
            contentItem.text = contentItem.text.replace(/confidential/gi, '[REDACTED]');
        }
    });
    
    // Log streaming progress
    const deltaLength = event?.delta?.content?.[0]?.text?.length || 0;
    console.log(`Delta chunk received: ${deltaLength} characters`);
    
    // Track streaming metrics
    trackStreamingMetrics({
        messageId: event.messageId,
        threadId: event.threadId,
        runId: event.runId,
        deltaLength: deltaLength,
        timestamp: Date.now()
    });
});

The following example suppress delta rendering:

instance.on('pre:stream:delta', (event, instance) => {
    // Suppress delta rendering by emptying the content array
    // Streaming still occurs, but text won't appear character by character
    // Only the final complete message will be rendered
    event.delta.content = [];
    
    console.log('Delta rendering suppressed - final message will render after streaming completes');
});

The following example shows the translation pattern:

let shouldSuppressDeltas = true;

instance.on('pre:stream:delta', (event, instance) => {
    // Suppress deltas during streaming
    if (shouldSuppressDeltas) {
        event.delta.content = [];
    }
});

instance.on('pre:receive', (event, instance) => {
    // Translate the complete message before rendering
    event?.message?.content?.forEach((contentItem) => {
        if (contentItem.response_type === 'text' && contentItem.text) {
            // Apply translation to complete message
            contentItem.text = translateText(contentItem.text);
        }
    });
});

Considerations

Event behavior

Multiple handlers can be registered and will run in registration order.
The delta.content array contains only the incremental content for the current chunk, not the complete message.
The message object (when available) accumulates all previous deltas and represents the message state so far.

Use cases

Content filtering: Remove or redact sensitive information in real-time as it streams.
Text transformation: Apply formatting or transformations to streaming content.
Suppress streaming: Disable character-by-character streaming and show only the final message.
Translation workflows: Suppress deltas and translate the complete message in pre:receive.
Progress tracking: Monitor streaming progress and display custom loading indicators.
Analytics: Track streaming performance metrics like chunk size and frequency.

Do you need practical examples?

Learn how to apply the features available for embedded chat into your implementation with guidance and examples.

Release Notes

Get Started

Build

Deploy

Analyze

Developer experience

Legal notices

Event properties

Examples

Considerations

Event behavior

Use cases

Do you need practical examples?

​Event properties

​Examples

​Considerations

​Event behavior

​Use cases

Do you need practical examples?

Event properties

Examples

Considerations

Event behavior

Use cases