@carbon/ai-chat 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,4434 @@
1
+ import { NOTIFICATION_KIND } from '@carbon/web-components/es/components/notification/defs.js';
2
+ import { BUTTON_KIND } from '@carbon/web-components/es/components/button/defs.js';
3
+ import { ReactNode } from 'react';
4
+ import * as lit_html from 'lit-html';
5
+ import { LitElement, PropertyValues } from 'lit';
6
+ import { Root } from 'react-dom/client';
7
+
8
+ /**
9
+ * Whether a particular Carbon AI Chat view is visible or not.
10
+ *
11
+ * @category Instance
12
+ */
13
+ interface ViewState {
14
+ /**
15
+ * Whether the launcher is visible or not.
16
+ */
17
+ launcher: boolean;
18
+ /**
19
+ * Whether the main window is visible or not.
20
+ */
21
+ mainWindow: boolean;
22
+ }
23
+ /**
24
+ * A record of a notification to be shown in the UI.
25
+ *
26
+ * @experimental
27
+ * @category Instance
28
+ */
29
+ interface NotificationMessage {
30
+ kind: NOTIFICATION_KIND;
31
+ /**
32
+ * The title to show in the message.
33
+ */
34
+ title: string;
35
+ /**
36
+ * The message to show.
37
+ */
38
+ message: string;
39
+ /**
40
+ * An optional action button that a user can click. If there is an action button, we will not auto dismiss.
41
+ */
42
+ actionButtonLabel?: string;
43
+ /**
44
+ * The group id that associates notifications together. This can be used to remove the notification later.
45
+ */
46
+ groupID?: string;
47
+ /**
48
+ * The callback called when someone clicks on the action button.
49
+ */
50
+ onActionButtonClick?: () => void;
51
+ /**
52
+ * The callback called when someone clicks on the close button.
53
+ */
54
+ onCloseButtonClick?: () => void;
55
+ }
56
+ /**
57
+ * The different views that can be shown by Carbon AI Chat.
58
+ *
59
+ * @category Instance
60
+ */
61
+ declare enum ViewType {
62
+ /**
63
+ * The launcher view is used to open the main window.
64
+ */
65
+ LAUNCHER = "launcher",
66
+ /**
67
+ * The main window view is used to ask WA questions and converse with an agent, as well as many other things. The
68
+ * string value is kept camel case to align with the viewState mainWindow property.
69
+ */
70
+ MAIN_WINDOW = "mainWindow"
71
+ }
72
+ /**
73
+ * This manager handles fetching an instance for manipulating the custom panel.
74
+ *
75
+ * @category Instance
76
+ */
77
+ interface CustomPanels {
78
+ /**
79
+ * Gets a custom panel instance.
80
+ */
81
+ getPanel: () => CustomPanelInstance;
82
+ }
83
+ /**
84
+ * The custom panel instance for controlling and manipulating a custom panel in Carbon AI Chat.
85
+ *
86
+ * @category Instance
87
+ */
88
+ interface CustomPanelInstance {
89
+ /**
90
+ * The custom panel hostElement.
91
+ */
92
+ hostElement?: HTMLDivElement | undefined;
93
+ /**
94
+ * Opens the custom panel.
95
+ *
96
+ * @param options Custom panel options.
97
+ */
98
+ open: (options?: CustomPanelConfigOptions) => void;
99
+ /**
100
+ * Closes the custom panel.
101
+ */
102
+ close: () => void;
103
+ }
104
+ /**
105
+ * Describes general config options for a Carbon AI Chat panel. These options are also part of the
106
+ * {@link BasePanelComponentProps}, except the options here are also shared with {@link CustomPanelConfigOptions}.
107
+ *
108
+ * Any options specific to either the BasePanelComponent or CustomPanelConfigOptions should be added to the respective
109
+ * interface.
110
+ *
111
+ * @category Instance
112
+ */
113
+ interface BasePanelConfigOptions {
114
+ /**
115
+ * The panel title which is left blank by default.
116
+ */
117
+ title?: string;
118
+ /**
119
+ * Indicates if the close button in the custom panel should be hidden.
120
+ */
121
+ hideCloseButton?: boolean;
122
+ /**
123
+ * Indicates if the panel header should be hidden.
124
+ */
125
+ hidePanelHeader?: boolean;
126
+ /**
127
+ * Indicates if the back button in the custom panel should be hidden.
128
+ */
129
+ hideBackButton?: boolean;
130
+ /**
131
+ * This callback is called when the close button is clicked. This is called even if {@link disableDefaultCloseAction}
132
+ * is set to true.
133
+ */
134
+ onClickClose?: () => void;
135
+ /**
136
+ * Called when the restart button is clicked.
137
+ */
138
+ onClickRestart?: () => void;
139
+ /**
140
+ * This callback is called when the back button is clicked.
141
+ */
142
+ onClickBack?: () => void;
143
+ }
144
+ /**
145
+ * Options that change how the custom panel looks.
146
+ *
147
+ * @category Instance
148
+ */
149
+ interface CustomPanelConfigOptions extends BasePanelConfigOptions {
150
+ /**
151
+ * Determines if the panel open/close animation should be turned off.
152
+ */
153
+ disableAnimation?: boolean;
154
+ /**
155
+ * Disables the default action that is taken when the close button is clicked. The default
156
+ * action closes Carbon AI Chat and disabling this will cause the button to not do anything. You can override the button
157
+ * behavior by using the {@link onClickClose} callback.
158
+ */
159
+ disableDefaultCloseAction?: boolean;
160
+ }
161
+
162
+ /*
163
+ * Copyright IBM Corp. 2025
164
+ *
165
+ * This source code is licensed under the Apache-2.0 license found in the
166
+ * LICENSE file in the root directory of this source tree.
167
+ *
168
+ * @license
169
+ */
170
+
171
+ /**
172
+ * Utility type that makes all properties in T optional recursively.
173
+ *
174
+ * This type is useful for configuration objects where you want to allow
175
+ * partial updates to nested object structures. It recursively applies
176
+ * the optional modifier (?) to all properties, including nested objects.
177
+ *
178
+ * @template T - The type to make deeply partial
179
+ *
180
+ * @example
181
+ * ```typescript
182
+ * interface Config {
183
+ * server: {
184
+ * host: string;
185
+ * port: number;
186
+ * };
187
+ * database: {
188
+ * url: string;
189
+ * timeout: number;
190
+ * };
191
+ * }
192
+ *
193
+ * // All properties become optional, including nested ones
194
+ * const partialConfig: DeepPartial<Config> = {
195
+ * server: {
196
+ * host: "localhost" // port is optional
197
+ * }
198
+ * // database is optional entirely
199
+ * };
200
+ * ```
201
+ *
202
+ * @category Utilities
203
+ */
204
+ type DeepPartial<T> = {
205
+ [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
206
+ };
207
+
208
+ /**
209
+ * The different type of error states a given message can be in.
210
+ *
211
+ * @category Messaging
212
+ */
213
+ declare enum MessageErrorState {
214
+ /**
215
+ * No errors.
216
+ */
217
+ NONE = 1,
218
+ /**
219
+ * The message failed to be sent and no more attempts will be made.
220
+ */
221
+ FAILED = 2,
222
+ /**
223
+ * The message failed while streaming.
224
+ */
225
+ FAILED_WHILE_STREAMING = 3,
226
+ /**
227
+ * There was an error sending the message but the system is retrying the message.
228
+ */
229
+ RETRYING = 4,
230
+ /**
231
+ * Indicates that the previous message has entered the retrying state and that this message is waiting for it to
232
+ * finish or fail. This message will remain in the waiting state until it finishes successfully or it enters a
233
+ * retrying state itself.
234
+ */
235
+ WAITING = 5
236
+ }
237
+
238
+ /**
239
+ * This file contains the generic types for the API between a general chat widget and a chat back-end. It is
240
+ * intended to provide base types for a standalone widget and should not contain any imports of other types.
241
+ */
242
+
243
+ /**
244
+ * This is the main interface that represents a request from a user sent to an assistant.
245
+ *
246
+ * @category Messaging
247
+ */
248
+ interface MessageRequest<TInputType extends BaseMessageInput = MessageInput> {
249
+ /**
250
+ * The unique identifier for this request object. This value may be assigned by the client when a request is
251
+ * made but should be assigned by the service if one is not provided.
252
+ */
253
+ id?: string;
254
+ /**
255
+ * The history information to store as part of this request. This includes extra information that was provided to
256
+ * the user and about the user that was used in making the request.
257
+ */
258
+ history?: MessageRequestHistory;
259
+ /**
260
+ * The input data to the back-end to make in this request.
261
+ */
262
+ input: TInputType;
263
+ /**
264
+ * Optional context which is added from external resources.
265
+ */
266
+ context?: unknown;
267
+ /**
268
+ * The ID of the thread this request belongs to. This is here to prepare for input message editing and regenerating
269
+ * responses.
270
+ */
271
+ thread_id?: string;
272
+ }
273
+ /**
274
+ * The set of possible message input types in a request.
275
+ *
276
+ * @category Messaging
277
+ */
278
+ declare enum MessageInputType {
279
+ /**
280
+ * Represents a simple text message.
281
+ */
282
+ TEXT = "text",
283
+ /**
284
+ * Represents an event message that can be used to send control, updates, or action information to the back-end.
285
+ */
286
+ EVENT = "event"
287
+ }
288
+ /**
289
+ * @category Messaging
290
+ */
291
+ interface BaseMessageInput {
292
+ /**
293
+ * The type of user input.
294
+ */
295
+ message_type?: MessageInputType;
296
+ }
297
+ /**
298
+ * Base interface for an event message that can be used to send control, updates, or action information to the back-end.
299
+ *
300
+ * @category Messaging
301
+ */
302
+ interface EventInput<TEventInputType = EventInputData> extends BaseMessageInput {
303
+ /**
304
+ * Event messages have this as their input type.
305
+ */
306
+ message_type: MessageInputType.EVENT;
307
+ /**
308
+ * The type of the event.
309
+ */
310
+ event: TEventInputType;
311
+ }
312
+ /**
313
+ * Input for an event. The name of the event is mandatory. Additional fields depend on the event.
314
+ *
315
+ * @template TNameType The type of the name property for the event. This can just be a string or it can be a
316
+ * specific string in order to create type safety ensuring each event has the right name (e.g. "typeof MY_EVENT_NAME").
317
+ *
318
+ * @category Messaging
319
+ */
320
+ interface EventInputData<TNameType extends string = string> {
321
+ /**
322
+ * The name of the event.
323
+ */
324
+ name: TNameType;
325
+ }
326
+ /**
327
+ * The default interface for message input that is sent to an assistant in a message request. This represents basic text
328
+ * input.
329
+ *
330
+ * @category Messaging
331
+ */
332
+ interface MessageInput extends BaseMessageInput {
333
+ /**
334
+ * The text of the user input to send to the back-end.
335
+ */
336
+ text?: string;
337
+ /**
338
+ * For messages that are sent between the user and a human agent, we assign an agent type to the message to distinguish what type it is.
339
+ */
340
+ agent_message_type?: HumanAgentMessageType;
341
+ }
342
+ /**
343
+ * This interface represents the main response content that is received by a client from an assistant. It is generally
344
+ * in response to a previous message request.
345
+ *
346
+ * @category Messaging
347
+ */
348
+ interface MessageResponse<TGenericType = GenericItem[]> {
349
+ /**
350
+ * A unique identifier for this response object.
351
+ */
352
+ id?: string;
353
+ /**
354
+ * The id of the request that this is the response of.
355
+ */
356
+ request_id?: string;
357
+ /**
358
+ * The output from the back-end to be rendered or processed by the client.
359
+ */
360
+ output: MessageOutput<TGenericType>;
361
+ /**
362
+ * The context information returned by the back-end.
363
+ */
364
+ context?: unknown;
365
+ /**
366
+ * The ID of the thread this request belongs to. This is here to prepare for input message editing and regenerating
367
+ * responses.
368
+ */
369
+ thread_id?: string;
370
+ /**
371
+ * The history information to store as part of this request.
372
+ */
373
+ history?: MessageResponseHistory;
374
+ /**
375
+ * Options for the {@link MessageResponse}. This includes metadata about the user or assistant sending this response.
376
+ */
377
+ message_options?: MessageResponseOptions;
378
+ }
379
+ /**
380
+ * The output context for a message response from an assistant.
381
+ *
382
+ * @category Messaging
383
+ */
384
+ interface MessageOutput<TGenericType = GenericItem[]> {
385
+ /**
386
+ * Responses intended to be processed by a generic channel. This will be an array of message response items.
387
+ */
388
+ generic?: TGenericType;
389
+ }
390
+ /**
391
+ * The set of possible message types in a response.
392
+ *
393
+ * @category Messaging
394
+ */
395
+ declare enum MessageResponseTypes {
396
+ /**
397
+ * Represents a basic text response. The given text may contain rich content such as markdown.
398
+ */
399
+ TEXT = "text",
400
+ /**
401
+ * A response that requests the user choose an option from a list. The list of options may be presented as a list
402
+ * of buttons or it may be from a drop-down.
403
+ */
404
+ OPTION = "option",
405
+ /**
406
+ * Indicates that the conversation should be escalated to a human agent and offers that opportunity to the user.
407
+ */
408
+ CONNECT_TO_HUMAN_AGENT = "connect_to_agent",
409
+ /**
410
+ * Displays an image to the user.
411
+ */
412
+ IMAGE = "image",
413
+ /**
414
+ * Indicates that the chat should display a pause at this point in the conversation before displaying additional
415
+ * items.
416
+ */
417
+ PAUSE = "pause",
418
+ /**
419
+ * A user defined response will be displayed according to custom logic in the client.
420
+ */
421
+ USER_DEFINED = "user_defined",
422
+ /**
423
+ * Displays the contents of an iframe to the user.
424
+ */
425
+ IFRAME = "iframe",
426
+ /**
427
+ * Displays a video to the user using a video player.
428
+ */
429
+ VIDEO = "video",
430
+ /**
431
+ * Displays an audio clip to the user using an audio player.
432
+ */
433
+ AUDIO = "audio",
434
+ /**
435
+ * Asks the user to provide a date. This may result in a date picker being presented to the user.
436
+ */
437
+ DATE = "date",
438
+ /**
439
+ * Displays a general error message to the user and include developer info to be logged and to debug.
440
+ */
441
+ INLINE_ERROR = "inline_error",
442
+ /**
443
+ * Displays a card that can contain other response types.
444
+ */
445
+ CARD = "card",
446
+ /**
447
+ * Displays a carousel of cards that can contain other response types.
448
+ */
449
+ CAROUSEL = "carousel",
450
+ /**
451
+ * Displays a button that can either send a message back to the backend, open a url, or throw a client side event.
452
+ */
453
+ BUTTON = "button",
454
+ /**
455
+ * Ability to layout response types inside a grid.
456
+ */
457
+ GRID = "grid",
458
+ /**
459
+ * Ability to show citations on your RAG result.
460
+ */
461
+ CONVERSATIONAL_SEARCH = "conversational_search"
462
+ }
463
+ /**
464
+ * These are the human agent specific message types.
465
+ *
466
+ * @category Service desk
467
+ */
468
+ declare enum HumanAgentMessageType {
469
+ /**
470
+ * There was an error in a message.
471
+ */
472
+ INLINE_ERROR = "inline_error",
473
+ /**
474
+ * The agent sent a message.
475
+ */
476
+ FROM_HUMAN_AGENT = "from_agent",
477
+ /**
478
+ * The user sent a message.
479
+ */
480
+ FROM_USER = "from_user",
481
+ /**
482
+ * The agent left the chat.
483
+ */
484
+ HUMAN_AGENT_LEFT_CHAT = "agent_left_chat",
485
+ /**
486
+ * The agent ended the conversation.
487
+ */
488
+ HUMAN_AGENT_ENDED_CHAT = "agent_ended_chat",
489
+ /**
490
+ * The agent joined the conversation.
491
+ */
492
+ HUMAN_AGENT_JOINED = "agent_joined",
493
+ /**
494
+ * A disconnection warning was emitted.
495
+ */
496
+ RELOAD_WARNING = "user_connected_warning",
497
+ /**
498
+ * The conversation was transferred to another agent.
499
+ */
500
+ TRANSFER_TO_HUMAN_AGENT = "transfer_to_agent",
501
+ /**
502
+ * The end user ended the conversation with the agent.
503
+ */
504
+ USER_ENDED_CHAT = "user_ended_chat",
505
+ /**
506
+ * The conversation was ended.
507
+ */
508
+ CHAT_WAS_ENDED = "chat_was_ended",
509
+ /**
510
+ * The conversation was disconnected.
511
+ */
512
+ DISCONNECTED = "disconnected",
513
+ /**
514
+ * The conversation was re-connected.
515
+ */
516
+ RECONNECTED = "reconnected",
517
+ /**
518
+ * Screen sharing requested.
519
+ */
520
+ SHARING_REQUESTED = "sharing_requested",
521
+ /**
522
+ * Screen sharing accepted.
523
+ */
524
+ SHARING_ACCEPTED = "sharing_accepted",
525
+ /**
526
+ * Screen sharing declined.
527
+ */
528
+ SHARING_DECLINED = "sharing_declined",
529
+ /**
530
+ * Screen sharing cancelled.
531
+ */
532
+ SHARING_CANCELLED = "sharing_cancelled",
533
+ /**
534
+ * Screen sharing ended.
535
+ */
536
+ SHARING_ENDED = "sharing_ended",
537
+ /**
538
+ * A system message.
539
+ */
540
+ SYSTEM = "system"
541
+ }
542
+ /**
543
+ * A general type to indicate any message.
544
+ *
545
+ * @category Messaging
546
+ */
547
+ type Message = MessageRequest<MessageInput> | MessageRequest<EventInput> | MessageResponse;
548
+ /**
549
+ * @category Messaging
550
+ */
551
+ interface ItemStreamingMetadata {
552
+ /**
553
+ * An identifier for this item within the full message response. This ID is used to correlate a partial or
554
+ * complete item chunk with other chunks that represent the same item. This ID is only unique for a given message
555
+ * response.
556
+ */
557
+ id: string;
558
+ /**
559
+ * When included on a partial_item, indicates if the stream can be cancelled.
560
+ * If so, a "stop streaming" button will display in the UI.
561
+ */
562
+ cancellable?: boolean;
563
+ /**
564
+ * Indicates if the stream has stopped which will trigger the UI to respond with appropriate a11y states
565
+ * and messaging.
566
+ */
567
+ stream_stopped?: boolean;
568
+ }
569
+ /**
570
+ * Status of the chain of thought step.
571
+ *
572
+ * @category Messaging
573
+ */
574
+ declare enum ChainOfThoughtStepStatus {
575
+ PROCESSING = "processing",
576
+ FAILURE = "failure",
577
+ SUCCESS = "success"
578
+ }
579
+ /**
580
+ * A chain of thought step is meant to show tool calls and other steps made by your agent
581
+ * to reach its final answer.
582
+ *
583
+ * @category Messaging
584
+ */
585
+ interface ChainOfThoughtStep {
586
+ /**
587
+ * The plain text name of the step.
588
+ */
589
+ title?: string;
590
+ /**
591
+ * An optional human readable description of what the tool does.
592
+ *
593
+ * Accepts markdown formatted text.
594
+ */
595
+ description?: string;
596
+ /**
597
+ * The plain text name of the tool called.
598
+ */
599
+ tool_name?: string;
600
+ /**
601
+ * Optional request metadata sent to a tool.
602
+ */
603
+ request?: {
604
+ /**
605
+ * Arguments sent to the tool. If this is properly formed JSON, it will be shown as a code block.
606
+ */
607
+ args?: unknown;
608
+ };
609
+ /**
610
+ * Optional response from a tool.
611
+ */
612
+ response?: {
613
+ /**
614
+ * Content returned by the tool. If this is properly formed JSON, it will be shown as a code block.
615
+ *
616
+ * You can also return markdown compatible text here.
617
+ */
618
+ content: unknown;
619
+ };
620
+ /**
621
+ * Optionally, share the status of this step. An icon will appear in the view showing the status. If no status is
622
+ * shared, the UI will assume success.
623
+ */
624
+ status?: ChainOfThoughtStepStatus;
625
+ }
626
+ /**
627
+ * Options that control additional features available for a message item.
628
+ *
629
+ * @category Messaging
630
+ */
631
+ interface GenericItemMessageOptions {
632
+ /**
633
+ * Controls the display of feedback options (thumbs up/down) for a message item.
634
+ */
635
+ feedback?: GenericItemMessageFeedbackOptions;
636
+ }
637
+ /**
638
+ * If you want to have different categories for positive and negative feedback, you can provide two different arrays.
639
+ *
640
+ * You may not provide one of the arrays. e.g. you want negative categories but don't care about positive categories.
641
+ *
642
+ * @category Messaging
643
+ */
644
+ interface GenericItemMessageFeedbackCategories {
645
+ /**
646
+ * List of strings for positive feedback categories.
647
+ */
648
+ positive?: string[];
649
+ /**
650
+ * List of strings for negative feedback categories.
651
+ */
652
+ negative?: string[];
653
+ }
654
+ /**
655
+ * Controls the display of a feedback options (thumbs up/down) for a message item.
656
+ *
657
+ * @category Messaging
658
+ */
659
+ interface GenericItemMessageFeedbackOptions {
660
+ /**
661
+ * Indicates if a request for feedback should be displayed.
662
+ */
663
+ is_on?: boolean;
664
+ /**
665
+ * A unique identifier for this feedback. This is required for the feedback to be recorded in message history.
666
+ */
667
+ id?: string;
668
+ /**
669
+ * Indicates if the user should be asked for additional detailed information when providing positive feedback. This
670
+ * defaults to true.
671
+ */
672
+ show_positive_details?: boolean;
673
+ /**
674
+ * Indicates if the user should be asked for additional detailed information when providing negative feedback. This
675
+ * defaults to true.
676
+ */
677
+ show_negative_details?: boolean;
678
+ /**
679
+ * Indicates whether the text area should be shown. This defaults to true.
680
+ */
681
+ show_text_area?: boolean;
682
+ /**
683
+ * Indicates whether the prompt line should be shown. This defaults to true.
684
+ */
685
+ show_prompt?: boolean;
686
+ /**
687
+ * The title to display in the popup. A default value will be used if no value is provided here.
688
+ */
689
+ title?: string;
690
+ /**
691
+ * The prompt text to display to the user. A default value will be used if no value is provided here.
692
+ */
693
+ prompt?: string;
694
+ /**
695
+ * An optional set of categories to allow the user to choose from. This can either be an array of strings for
696
+ * both positive and negative feedback or a {@link GenericItemMessageFeedbackCategories} object to make different
697
+ * configuration for both.
698
+ */
699
+ categories?: string[] | GenericItemMessageFeedbackCategories;
700
+ /**
701
+ * The placeholder to show in the text area. A default value will be used if no value is provided here.
702
+ */
703
+ placeholder?: string;
704
+ /**
705
+ * The legal disclaimer text to show at the bottom of the popup. This text may contain rich markdown content. If this
706
+ * value is not provided, no text will be shown.
707
+ */
708
+ disclaimer?: string;
709
+ }
710
+ /**
711
+ * @category Messaging
712
+ */
713
+ type PartialOrCompleteItemChunk = PartialItemChunk | CompleteItemChunk;
714
+ /**
715
+ * The base interface that all message response items must implement. Contains common properties
716
+ * shared by all item types.
717
+ *
718
+ * @category Messaging
719
+ */
720
+ interface BaseGenericItem<TUserDefinedType = Record<string, unknown>> {
721
+ /**
722
+ * The response type of this message item.
723
+ */
724
+ response_type: MessageResponseTypes;
725
+ /**
726
+ * Metadata used to identify a generic item within the context of a stream in order to correlate any updates meant
727
+ * for a specific item.
728
+ */
729
+ streaming_metadata?: ItemStreamingMetadata;
730
+ /**
731
+ * An optional buckets of additional user defined properties for this item.
732
+ */
733
+ user_defined?: TUserDefinedType;
734
+ /**
735
+ * For messages that are sent between the user and a human agent, we assign an agent type to the message to distinguish what type it is.
736
+ */
737
+ agent_message_type?: HumanAgentMessageType;
738
+ /**
739
+ * Options that control additional features available for a message item.
740
+ */
741
+ message_item_options?: GenericItemMessageOptions;
742
+ }
743
+ /**
744
+ * The basic class for items returned from an assistant as part of a message response. These are the items contained
745
+ * in the {@link MessageOutput.generic} array.
746
+ *
747
+ * @category Messaging
748
+ */
749
+ type GenericItem<TUserDefinedType = Record<string, unknown>> = TextItem<TUserDefinedType> | OptionItem<TUserDefinedType> | ConnectToHumanAgentItem<TUserDefinedType> | ImageItem<TUserDefinedType> | PauseItem<TUserDefinedType> | UserDefinedItem<TUserDefinedType> | IFrameItem<TUserDefinedType> | VideoItem<TUserDefinedType> | AudioItem<TUserDefinedType> | DateItem<TUserDefinedType> | InlineErrorItem<TUserDefinedType> | CardItem<TUserDefinedType> | CarouselItem<TUserDefinedType> | ButtonItem<TUserDefinedType> | GridItem<TUserDefinedType> | ConversationalSearchItem<TUserDefinedType>;
750
+ /**
751
+ * A user defined item returned in a message response from an assistant.
752
+ *
753
+ * @category Messaging
754
+ */
755
+ interface UserDefinedItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
756
+ /**
757
+ * If the user_defined response type should be rendered as full width and ignore margin on the "start".
758
+ */
759
+ full_width?: boolean;
760
+ }
761
+ /**
762
+ * A text item returned in a message response from an assistant.
763
+ *
764
+ * The Carbon AI Chat supports basic styling inside text responses to match the theme of your Carbon AI Chat,
765
+ * both with Markdown or HTML content returned from your assistant. Using Markdown and `user_defined`
766
+ * ({@link UserDefinedItem}) responses instead of HTML in your text responses is the recommendation. It allows
767
+ * adding channels that do not support HTML (such as Facebook, Slack, or WhatsApp) without having to rewrite
768
+ * your content.
769
+ *
770
+ * ## Markdown
771
+ *
772
+ * The Carbon AI Chat supports the following Markdown syntax in the text response type:
773
+ *
774
+ * **Text formatting:**
775
+ *
776
+ * - `**bold text**` or `__bold text__`
777
+ * - `*italic text*` or `_italic text_`
778
+ * - `~~strikethrough~~`
779
+ * - `==highlighted text==`
780
+ * - `^superscript^`
781
+ * - `~subscript~`
782
+ *
783
+ * **Code:**
784
+ *
785
+ * - `` `inline code` `` or fenced code blocks with syntax highlighting.
786
+ *
787
+ * **Headers:**
788
+ *
789
+ * - `# H1`, `## H2`, `### H3`, `#### H4`, `##### H5`, `###### H6`
790
+ *
791
+ * **Lists:**
792
+ *
793
+ * - Unordered lists using `*`, `+`, or `-`
794
+ * - Ordered lists using `1.`, `2.`, etc.
795
+ * - Nested lists are supported
796
+ *
797
+ * **Links and images:**
798
+ *
799
+ * - `[link text](URL)` for links (opens in new tab by default)
800
+ * - `![alt text](image URL)` for images
801
+ *
802
+ * **Other elements:**
803
+ *
804
+ * - `> blockquote text` for blockquotes
805
+ * - Tables using pipe syntax with automatic pagination and sorting
806
+ * - Horizontal rules using `---` or `***`
807
+ * - Line breaks are preserved (breaks: true)
808
+ * - Automatic URL detection and conversion to links
809
+ *
810
+ * **Attributes:**
811
+ *
812
+ * - Custom attributes using `{{class="my-class" id="my-id"}}` syntax
813
+ * - Supported attributes: `target`, `rel`, `class`, `id`
814
+ *
815
+ * **HTML support:**
816
+ *
817
+ * - Raw HTML is supported when enabled
818
+ * - Custom elements and web components are allowed
819
+ * - Content is sanitized for security when sanitization is enabled
820
+ *
821
+ * The Carbon AI Chat follows CommonMark rules with these extensions and enhancements.
822
+ *
823
+ * ## HTML content
824
+ *
825
+ * If you include HTML (including `style` and `script` tags) in your text response from your assistant, the
826
+ * Carbon AI Chat renders those elements as provided, unless you set {@link PublicConfig.shouldSanitizeHTML}
827
+ * to `true`. A better approach is to use a `user_defined` response instead of adding HTML directly to your
828
+ * responses to make adding support for channels that do not support HTML easier.
829
+ *
830
+ * @category Messaging
831
+ */
832
+ interface TextItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
833
+ /**
834
+ * The text of the response.
835
+ */
836
+ text?: string;
837
+ }
838
+ /**
839
+ * A "connect to agent" item returned in a message response from an assistant. This is used when the back-end
840
+ * indicates that a user's conversation should be escalated to a human agent.
841
+ *
842
+ * @category Messaging
843
+ */
844
+ interface ConnectToHumanAgentItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
845
+ /**
846
+ * A message to be sent to the human agent who will be taking over the conversation.
847
+ */
848
+ message_to_human_agent?: string;
849
+ /**
850
+ * Contains the message to be rendered if there are agents available.
851
+ */
852
+ agent_available?: {
853
+ message: string;
854
+ };
855
+ /**
856
+ * Contains the message to be rendered if there are no agents available.
857
+ */
858
+ agent_unavailable?: {
859
+ message: string;
860
+ };
861
+ /**
862
+ * When a conversation is escalated to an agent additional information is needed to fulfill the request. This
863
+ * additional information typically is added by the channel integration and cannot be deduced from the dialog
864
+ * itself.
865
+ */
866
+ transfer_info?: ConnectToHumanAgentItemTransferInfo;
867
+ }
868
+ /**
869
+ * Additional information as part of a {@link ConnectToHumanAgentItem} that may be needed to perform a transfer to an agent.
870
+ *
871
+ * @category Messaging
872
+ */
873
+ interface ConnectToHumanAgentItemTransferInfo {
874
+ /**
875
+ * Each service desk may require different information to start the connection. It can be account details or
876
+ * security information. This is a bucket of all the service desk specific properties.
877
+ */
878
+ additional_data?: {
879
+ [key: string]: string;
880
+ };
881
+ /**
882
+ * An initial set of message items to send to the agent.
883
+ */
884
+ summary_message_to_agent?: TextItem[];
885
+ }
886
+ /**
887
+ * A pause item returned in a message response from an assistant. This indicates that the client should pause before
888
+ * displaying additional response items.
889
+ *
890
+ * @category Messaging
891
+ */
892
+ interface PauseItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
893
+ /**
894
+ * How long to pause, in milliseconds.
895
+ */
896
+ time?: number;
897
+ /**
898
+ * Whether to display an "is typing" indicator during the pause.
899
+ */
900
+ typing?: boolean;
901
+ }
902
+ /**
903
+ * An option item returned in a message response from an assistant. This response type is used when displaying a list
904
+ * of options to the user. How the options are displayed is up to the client but is often displayed in either a
905
+ * drop-down or as a list of buttons.
906
+ *
907
+ * @category Messaging
908
+ */
909
+ interface OptionItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
910
+ /**
911
+ * An array of objects describing the options from which the user can choose.
912
+ */
913
+ options: SingleOption[];
914
+ /**
915
+ * An optional title to be shown alongside the options.
916
+ */
917
+ title?: string;
918
+ /**
919
+ * An optional description to be shown alongside the options.
920
+ */
921
+ description?: string;
922
+ /**
923
+ * The preferred type of control to display (e.g. button or dropdown).
924
+ */
925
+ preference?: OptionItemPreference;
926
+ }
927
+ /**
928
+ * The set of possible response preferences for an options response.
929
+ *
930
+ * @category Messaging
931
+ */
932
+ declare enum OptionItemPreference {
933
+ /**
934
+ * Indicates the options should be displayed as a drop-down.
935
+ */
936
+ DROPDOWN = "dropdown",
937
+ /**
938
+ * Indicates the options should be displayed as buttons.
939
+ */
940
+ BUTTON = "button"
941
+ }
942
+ /**
943
+ * Represents an individual option that is part of an "options" response.
944
+ *
945
+ * @category Messaging
946
+ */
947
+ interface SingleOption {
948
+ /**
949
+ * The user-facing label for the option or disambiguation suggestion. This label is taken from the user_label property
950
+ * of the corresponding dialog node.
951
+ */
952
+ label: string;
953
+ value: {
954
+ /**
955
+ * An input object that should be sent back to the assistant when this option is chosen by a user.
956
+ */
957
+ input: MessageInput;
958
+ };
959
+ }
960
+ /**
961
+ * @category Messaging
962
+ */
963
+ interface IFrameItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
964
+ /**
965
+ * The source URL to an embeddable page
966
+ */
967
+ source: string;
968
+ /**
969
+ * The preview image of the source URL. This property is unfurled from the source URL at runtime. It is used when
970
+ * IFrameItemDisplayOption is set to 'panel' for the preview card to open the panel.
971
+ */
972
+ image_url?: string;
973
+ /**
974
+ * The title of the source URL. This property is unfurled from the source URL at runtime. It is used when
975
+ * IFrameItemDisplayOption is set to 'panel' for the preview card to open the panel.
976
+ */
977
+ title?: string;
978
+ /**
979
+ * The description of the source URL. This property is unfurled from the source URL at runtime. It is used when
980
+ * IFrameItemDisplayOption is set to 'panel' for the preview card to open the panel.
981
+ */
982
+ description?: string;
983
+ /**
984
+ * How the iframe should be displayed.
985
+ */
986
+ display?: IFrameItemDisplayOption;
987
+ }
988
+ /**
989
+ * Dimension information for displaying a media item.
990
+ *
991
+ * @category Messaging
992
+ */
993
+ interface MediaItemDimensions {
994
+ /**
995
+ * This property's value is used to calculate a responsive height for Carbon AI Chat's media player so that its aspect
996
+ * ratio is the same between different screen widths. This is set to a reasonable default depending on the response type
997
+ * and other details like what service you are pulling the content from (e.g. Youtube or SoundCloud).
998
+ */
999
+ base_height?: number;
1000
+ }
1001
+ /**
1002
+ * The different ways an iframe item may be displayed.
1003
+ *
1004
+ * @category Messaging
1005
+ */
1006
+ declare enum IFrameItemDisplayOption {
1007
+ /**
1008
+ * The iframe is displayed inline in the main message list.
1009
+ */
1010
+ INLINE = "inline",
1011
+ /**
1012
+ * The iframe is displayed in a separate panel after showing a card in the main message list.
1013
+ */
1014
+ PANEL = "panel"
1015
+ }
1016
+ /**
1017
+ * A reusable media object that may need to display a title and description with an alt_text to label the item for
1018
+ * accessibility purposes. This is used by the Audio, Video and Image response types.
1019
+ *
1020
+ * @category Messaging
1021
+ */
1022
+ interface MediaItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
1023
+ /**
1024
+ * The url pointing to a media source, whether audio, video, or image.
1025
+ *
1026
+ * For video this can be a file like an .mp4 or a YouTube, Facebook, Vimeo, Twitch, Streamable, Wistia, or Vidyard url.
1027
+ *
1028
+ * For audio this can be a file like an .mp3 or a SoundCloud or Mixcloud url.
1029
+ */
1030
+ source: string;
1031
+ /**
1032
+ * The title for the item.
1033
+ */
1034
+ title?: string;
1035
+ /**
1036
+ * The description for the item.
1037
+ */
1038
+ description?: string;
1039
+ /**
1040
+ * The alt text for labeling the item. Screen readers will announce this text when the user's virtual cursor
1041
+ * is focused on the item.
1042
+ */
1043
+ alt_text?: string;
1044
+ /**
1045
+ * Settings that control the dimensions for the media item.
1046
+ */
1047
+ dimensions?: MediaItemDimensions;
1048
+ }
1049
+ /**
1050
+ * Citations for text generated by an AI to provide the user with relevant source information and context.
1051
+ *
1052
+ * @category Messaging
1053
+ */
1054
+ interface ConversationalSearchItemCitation {
1055
+ /**
1056
+ * Optional url of the citation. May not be a valid URL.
1057
+ */
1058
+ url?: string;
1059
+ /**
1060
+ * Optional explanation text for the citation.
1061
+ */
1062
+ text?: string;
1063
+ /**
1064
+ * Optional title of the citation URL.
1065
+ */
1066
+ title?: string;
1067
+ /**
1068
+ * Optional array of ranges indicating where in `text` the citation is located.
1069
+ */
1070
+ ranges?: {
1071
+ start: number;
1072
+ end: number;
1073
+ }[];
1074
+ /**
1075
+ * In some implementations, the content searched isn't in an accessible URL. For instance, it could be from Milvus or
1076
+ * ElasticSearch. In that scenario, you may populate "search_results". This field will allow you define which index in
1077
+ * the search_results array matches with this citation. The end user can then drill into the larger search result to
1078
+ * view it rather than clicking on a URL to actually see the content.
1079
+ */
1080
+ search_result_idx?: number;
1081
+ }
1082
+ /**
1083
+ * A text response generated by AI with an optional list of citations for where the information came from.
1084
+ *
1085
+ * @category Messaging
1086
+ */
1087
+ interface ConversationalSearchItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
1088
+ /**
1089
+ * The returned conversational text. Any HTML/Markdown will be ignored.
1090
+ */
1091
+ text: string;
1092
+ /**
1093
+ * Citations are used to connect specific text within a conversational search response with the relevant documents
1094
+ * returned by the backend.
1095
+ */
1096
+ citations?: ConversationalSearchItemCitation[];
1097
+ /**
1098
+ * In some implementations, the content searched isn't in an accessible URL. For instance, it could be from Milvus or
1099
+ * ElasticSearch. In that scenario, you may populate "search_results". Combine this with
1100
+ * {@link ConversationalSearchItemCitation.search_result_idx}.
1101
+ */
1102
+ search_results?: SearchResult[];
1103
+ }
1104
+ /**
1105
+ * An inline error response generated by a conversational skill provider with a user-friendly text and developer debug info.
1106
+ *
1107
+ * @category Messaging
1108
+ */
1109
+ interface InlineErrorItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
1110
+ /**
1111
+ * Some end user friendly text describing the error and what they should do next.
1112
+ *
1113
+ * If no specific text is passed, the client is responsible for fallback generic error message text.
1114
+ */
1115
+ text?: string;
1116
+ /**
1117
+ * Relevant debug info intended to be passed on to developers.
1118
+ *
1119
+ * This information should not include anything sensitive that might reveal details about our back-end environment that should not be public.
1120
+ */
1121
+ debug?: {
1122
+ /**
1123
+ * The error code of any underlying error, despite the service returning 200.
1124
+ */
1125
+ statusCode?: number;
1126
+ /**
1127
+ * Developer-friendly error text.
1128
+ */
1129
+ text?: string;
1130
+ /**
1131
+ * Any additional key-value pairs for debugging.
1132
+ */
1133
+ info?: Record<string, unknown>;
1134
+ };
1135
+ }
1136
+ /**
1137
+ * The image response type definition. This is currently the same as {@link MediaItem}.
1138
+ *
1139
+ * @category Messaging
1140
+ */
1141
+ type ImageItem<TUserDefinedType = Record<string, unknown>> = MediaItem<TUserDefinedType>;
1142
+ /**
1143
+ * The video response type definition for future reuse. This is currently the same as {@link MediaItem}.
1144
+ *
1145
+ * @category Messaging
1146
+ */
1147
+ type VideoItem<TUserDefinedType = Record<string, unknown>> = MediaItem<TUserDefinedType>;
1148
+ /**
1149
+ * The audio response type definition for future reuse. This is currently the same as {@link MediaItem}.
1150
+ *
1151
+ * @category Messaging
1152
+ */
1153
+ type AudioItem<TUserDefinedType = Record<string, unknown>> = MediaItem<TUserDefinedType>;
1154
+ /**
1155
+ * @category Messaging
1156
+ */
1157
+ declare enum ButtonItemType {
1158
+ /**
1159
+ * A button that sends its value back to the backend.
1160
+ */
1161
+ POST_BACK = "post_back",
1162
+ /**
1163
+ * A button that throws an event for your UI to respond to.
1164
+ */
1165
+ CUSTOM_EVENT = "custom_event",
1166
+ /**
1167
+ * A button that shows a panel.
1168
+ */
1169
+ SHOW_PANEL = "show_panel",
1170
+ /**
1171
+ * A button that opens a URL.
1172
+ */
1173
+ URL = "url"
1174
+ }
1175
+ /**
1176
+ * @category Messaging
1177
+ */
1178
+ declare enum WidthOptions {
1179
+ /**
1180
+ * Width the size of the floating chat for smaller content.
1181
+ */
1182
+ SMALL = "small",
1183
+ /**
1184
+ * Max width of 438px, 2/3rd of the width of chat in fullscreen view with hasContentMaxWidth: true.
1185
+ */
1186
+ MEDIUM = "medium",
1187
+ /**
1188
+ * Max width of 585px, the full with of chat in fullscreen view with hasContentMaxWidth: true.
1189
+ */
1190
+ LARGE = "large"
1191
+ }
1192
+ /**
1193
+ * @category Messaging
1194
+ */
1195
+ interface WithWidthOptions {
1196
+ /**
1197
+ * Sets an optional max width of the component. Options are small, medium and large.
1198
+ * By default, the component will be 100% width of the container.
1199
+ */
1200
+ max_width?: WidthOptions;
1201
+ }
1202
+ /**
1203
+ * @category Messaging
1204
+ */
1205
+ interface WithBodyAndFooter {
1206
+ /**
1207
+ * A list of message items to render in a Carbon AI Chat panel.
1208
+ */
1209
+ body?: GenericItem[];
1210
+ /**
1211
+ * A list of button items that are rendered under the panel body.
1212
+ */
1213
+ footer?: ButtonItem[];
1214
+ }
1215
+ /**
1216
+ * @category Messaging
1217
+ */
1218
+ interface MessageItemPanelInfo extends WithBodyAndFooter {
1219
+ /**
1220
+ * The title to give the panel in Carbon AI Chat.
1221
+ */
1222
+ title?: string;
1223
+ /**
1224
+ * Determines if the panel header should not be visible or not.
1225
+ */
1226
+ show_header?: boolean;
1227
+ /**
1228
+ * Determines if the panel close and open animations should be enabled or not.
1229
+ */
1230
+ show_animations?: boolean;
1231
+ }
1232
+ /**
1233
+ * @category Messaging
1234
+ */
1235
+ declare enum ButtonItemKind {
1236
+ /**
1237
+ * Default Carbon button.
1238
+ */
1239
+ DEFAULT = "default",
1240
+ /**
1241
+ * Secondary Carbon button.
1242
+ */
1243
+ SECONDARY = "secondary",
1244
+ /**
1245
+ * Tertiary Carbon button.
1246
+ */
1247
+ TERTIARY = "tertiary",
1248
+ /**
1249
+ * Danger Carbon button.
1250
+ */
1251
+ DANGER = "danger",
1252
+ /**
1253
+ * Ghost Carbon button.
1254
+ */
1255
+ GHOST = "ghost",
1256
+ /**
1257
+ * Button displayed like a link.
1258
+ */
1259
+ LINK = "link"
1260
+ }
1261
+ /**
1262
+ * This message item represents a button that can perform various actions such as sending messages, opening URLs, or showing panels.
1263
+ *
1264
+ * @category Messaging
1265
+ */
1266
+ interface ButtonItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
1267
+ /**
1268
+ * The style of button to display.
1269
+ */
1270
+ kind?: BUTTON_KIND | "LINK";
1271
+ /**
1272
+ * The type of button.
1273
+ */
1274
+ button_type: ButtonItemType;
1275
+ /**
1276
+ * The URL for the user to visit when the button is clicked.
1277
+ */
1278
+ url?: string;
1279
+ /**
1280
+ * Where to open the link. The default value is _self.
1281
+ */
1282
+ target?: string;
1283
+ /**
1284
+ * The display text for the link.
1285
+ */
1286
+ label?: string;
1287
+ /**
1288
+ * A custom event that can be listened to by Carbon AI Chat when the button item is clicked.
1289
+ */
1290
+ custom_event_name?: string;
1291
+ value?: {
1292
+ /**
1293
+ * An input object that should be sent back to the assistant when this option is chosen by a user.
1294
+ */
1295
+ input: MessageInput;
1296
+ };
1297
+ /**
1298
+ * The panel options to display in a panel when the "show_panel" button type is clicked.
1299
+ */
1300
+ panel?: MessageItemPanelInfo;
1301
+ /**
1302
+ * The URL pointing to an image.
1303
+ */
1304
+ image_url?: string;
1305
+ /**
1306
+ * The alt text for labeling the item. Screen readers will announce this text when the user's virtual cursor
1307
+ * is focused on the item.
1308
+ */
1309
+ alt_text?: string;
1310
+ }
1311
+ /**
1312
+ * @category Messaging
1313
+ */
1314
+ type CardItem<TUserDefinedType = Record<string, unknown>> = BaseGenericItem<TUserDefinedType> & WithBodyAndFooter & WithWidthOptions;
1315
+ /**
1316
+ * @category Messaging
1317
+ */
1318
+ interface CarouselItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType> {
1319
+ items: GenericItem[];
1320
+ }
1321
+ /**
1322
+ * Horizontal alignment values for items in a grid response.
1323
+ *
1324
+ * @category Messaging
1325
+ */
1326
+ type HorizontalCellAlignment = "left" | "center" | "right";
1327
+ /**
1328
+ * Vertical alignment values for items in a grid response.
1329
+ *
1330
+ * @category Messaging
1331
+ */
1332
+ type VerticalCellAlignment = "top" | "center" | "bottom";
1333
+ /**
1334
+ * @category Messaging
1335
+ */
1336
+ interface GridItem<TUserDefinedType = Record<string, unknown>> extends BaseGenericItem<TUserDefinedType>, WithWidthOptions {
1337
+ /**
1338
+ * Determines the horizontal alignment of all items in the grid.
1339
+ */
1340
+ horizontal_alignment?: HorizontalCellAlignment;
1341
+ /**
1342
+ * Determines the vertical alignment of all items in the grid.
1343
+ */
1344
+ vertical_alignment?: VerticalCellAlignment;
1345
+ /**
1346
+ * The list of column specifications. This will determine the maximum number of columns that can be rendered.
1347
+ */
1348
+ columns: {
1349
+ width: string;
1350
+ }[];
1351
+ /**
1352
+ * A list of rows to render.
1353
+ */
1354
+ rows: {
1355
+ /**
1356
+ * A list of cells to render in a row.
1357
+ */
1358
+ cells: {
1359
+ /**
1360
+ * Determines the horizontal alignment of items in the individual cell.
1361
+ */
1362
+ horizontal_alignment?: HorizontalCellAlignment;
1363
+ /**
1364
+ * Determines the vertical alignment of items in the individual cell.
1365
+ */
1366
+ vertical_alignment?: VerticalCellAlignment;
1367
+ /**
1368
+ * Message items to render in the cell.
1369
+ */
1370
+ items: GenericItem[];
1371
+ }[];
1372
+ }[];
1373
+ }
1374
+ /**
1375
+ * This is the response item that represents a request for a date which should prompt the client to use a date picker or
1376
+ * similar control to provide a date. There are currently no additional properties of the response.
1377
+ *
1378
+ * @category Messaging
1379
+ */
1380
+ type DateItem<TUserDefinedType = Record<string, unknown>> = BaseGenericItem<TUserDefinedType>;
1381
+ /**
1382
+ * @category Messaging
1383
+ */
1384
+ interface Chunk {
1385
+ /**
1386
+ * Additional metadata associated with the stream.
1387
+ */
1388
+ streaming_metadata?: {
1389
+ /**
1390
+ * The ID of the complete message response object. This ID will be the ID of the full message that is received
1391
+ * in the final chunk of the stream.
1392
+ */
1393
+ response_id: string;
1394
+ };
1395
+ }
1396
+ /**
1397
+ * This interface contains options for a {@link MessageResponse}.
1398
+ *
1399
+ * @category Messaging
1400
+ */
1401
+ interface MessageResponseOptions {
1402
+ /**
1403
+ * This is the profile for the human or assistant who sent or triggered this message.
1404
+ */
1405
+ response_user_profile?: ResponseUserProfile;
1406
+ /**
1407
+ * Controls the display of the chain of thought component.
1408
+ */
1409
+ chain_of_thought?: ChainOfThoughtStep[];
1410
+ }
1411
+ /**
1412
+ * This interface contains information about the history of a given {@link MessageResponse}. This information should be
1413
+ * saved your history store.
1414
+ *
1415
+ * @category Messaging
1416
+ */
1417
+ interface MessageResponseHistory {
1418
+ /**
1419
+ * The time at which this message occurred.
1420
+ */
1421
+ timestamp?: number;
1422
+ /**
1423
+ * Indicates if this is a "silent" message. These messages are sent to or received from the assistant but should
1424
+ * not be displayed to the user.
1425
+ */
1426
+ silent?: boolean;
1427
+ /**
1428
+ * The error state of this message.
1429
+ */
1430
+ error_state?: MessageErrorState;
1431
+ /**
1432
+ * The state of feedback provided on the items in this message.
1433
+ */
1434
+ feedback?: {
1435
+ [feedbackID: string]: MessageHistoryFeedback;
1436
+ };
1437
+ }
1438
+ /**
1439
+ * This interface contains information about the history of a given {@link MessageRequest}. This information should be
1440
+ * saved your history store.
1441
+ *
1442
+ * @category Messaging
1443
+ */
1444
+ interface MessageRequestHistory {
1445
+ /**
1446
+ * The time at which this message occurred.
1447
+ */
1448
+ timestamp?: number;
1449
+ /**
1450
+ * The user-friendly label that was associated with this message. This is used on messages that were sent by the
1451
+ * user to the assistant to request a response. This is the user displayed text that was entered or selected by
1452
+ * the user when that request was made. Most commonly used to make sure a {@link OptionItem} shows the correct button
1453
+ * selected when loading history.
1454
+ */
1455
+ label?: string;
1456
+ /**
1457
+ * If the message was a welcome node request.
1458
+ */
1459
+ is_welcome_request?: boolean;
1460
+ /**
1461
+ * If this message is related to another message, this is the ID of that other message. This is used when a user
1462
+ * choices an option and it includes the ID of the message response that presented the options to the user so we
1463
+ * can associate the user's request with that earlier response and display the appropriate selected state.
1464
+ */
1465
+ related_message_id?: string;
1466
+ /**
1467
+ * Indicates if this is a "silent" message. These messages are sent to or received from the assistant but should
1468
+ * not be displayed to the user.
1469
+ */
1470
+ silent?: boolean;
1471
+ /**
1472
+ * The error state of this message.
1473
+ */
1474
+ error_state?: MessageErrorState;
1475
+ }
1476
+ /**
1477
+ * @category Messaging
1478
+ */
1479
+ interface MessageHistoryFeedback {
1480
+ /**
1481
+ * Indicates if positive feedback was provided.
1482
+ */
1483
+ is_positive: boolean;
1484
+ /**
1485
+ * The feedback text provided by the user.
1486
+ */
1487
+ text?: string;
1488
+ /**
1489
+ * When submitting feedback details, this is the list of categories the user selected (if visible).
1490
+ */
1491
+ categories?: string[];
1492
+ }
1493
+ /**
1494
+ * @category Messaging
1495
+ */
1496
+ interface PartialResponse {
1497
+ /**
1498
+ * This contains the history of this response.
1499
+ */
1500
+ message_options?: DeepPartial<MessageResponseOptions>;
1501
+ }
1502
+ /**
1503
+ * The interface for a chunk that represents a partial update (or first time chunk) to a message item.
1504
+ *
1505
+ * @category Messaging
1506
+ */
1507
+ interface PartialItemChunk extends Chunk {
1508
+ /**
1509
+ * The partial details of the item. The client will decide what rules to follow for merging this in with any
1510
+ * existing data for the same item (which is identified using the {@link ItemStreamingMetadata.id} property).
1511
+ */
1512
+ partial_item: DeepPartial<GenericItem>;
1513
+ /**
1514
+ * Change the agent display name and other items on the full response.
1515
+ */
1516
+ partial_response?: PartialResponse;
1517
+ }
1518
+ /**
1519
+ * A chunk that represents a complete update to a single message item within a streaming response.
1520
+ *
1521
+ * This chunk type exists to allow immediate replacement of a streaming item with its final, corrected version
1522
+ * before the entire message response is complete. This enables real-time corrections to individual items
1523
+ * (like fixing typos in streaming text) while other items in the same message may still be streaming.
1524
+ *
1525
+ * The item provided here should have all the data necessary to render the item including any data that was
1526
+ * previously received from partial chunks. This chunk may contain corrections to previous chunks.
1527
+ *
1528
+ * Use this when you need to finalize a specific item but the overall message response isn't ready yet.
1529
+ *
1530
+ * If you are only streaming a single item you can skip
1531
+ * this chunk type entirely. CompleteItemChunk is primarily useful when streaming multiple different message
1532
+ * items and you need to finalize one item while others are still streaming.
1533
+ *
1534
+ * For ending the entire streaming response en masse, use {@link FinalResponseChunk}.
1535
+ *
1536
+ * @category Messaging
1537
+ */
1538
+ interface CompleteItemChunk extends Chunk {
1539
+ complete_item: GenericItem;
1540
+ /**
1541
+ * Change the agent display name and other items on the full response.
1542
+ */
1543
+ partial_response?: PartialResponse;
1544
+ }
1545
+ /**
1546
+ * A chunk that represents the entire completed message response, signaling the end of streaming.
1547
+ *
1548
+ * This chunk type exists as the definitive way to close a streaming session and provide the final,
1549
+ * authoritative version of the complete message response. Unlike {@link CompleteItemChunk} which updates
1550
+ * individual items, this chunk finalizes the entire response and triggers cleanup of streaming UI states
1551
+ * (like hiding "stop streaming" buttons).
1552
+ *
1553
+ * The response provided here should have all the data necessary to render the response including any data
1554
+ * that was previously received from item chunks. This final response may contain corrections to previous chunks.
1555
+ *
1556
+ * Use this to signal that streaming is complete and provide the canonical final state of the entire message.
1557
+ * The ID of the message should match the ID that was previously provided by streaming_metadata.response_id.
1558
+ *
1559
+ * @category Messaging
1560
+ */
1561
+ interface FinalResponseChunk {
1562
+ final_response: MessageResponse;
1563
+ }
1564
+ /**
1565
+ * @category Messaging
1566
+ */
1567
+ type StreamChunk = PartialItemChunk | CompleteItemChunk | FinalResponseChunk;
1568
+ /**
1569
+ * Types of users we accept messages from.
1570
+ *
1571
+ * @category Messaging
1572
+ */
1573
+ declare enum UserType {
1574
+ /**
1575
+ * A message from a human.
1576
+ */
1577
+ HUMAN = "human",
1578
+ /**
1579
+ * A message from a non-watsonx assistant, used for interacting with assistants that are not backed by watsonx.
1580
+ *
1581
+ * Official guidance is to not use this for IBM products without explicit exception.
1582
+ */
1583
+ BOT = "bot",
1584
+ /**
1585
+ * A message from watsonx.
1586
+ */
1587
+ WATSONX = "watsonx"
1588
+ }
1589
+ /**
1590
+ * Profile information about a specific agent that can be used to display information to the user. This may
1591
+ * represent a human agent or a virtual assistant agent.
1592
+ *
1593
+ * @category Messaging
1594
+ */
1595
+ interface ResponseUserProfile {
1596
+ /**
1597
+ * A unique identifier for this agent.
1598
+ */
1599
+ id: string;
1600
+ /**
1601
+ * The visible name for the response author. Can be the full name or just a first name for a human.
1602
+ */
1603
+ nickname: string;
1604
+ /**
1605
+ * The type of user. If its a "human" there is more protection against code injection attacks, where as assistant responses
1606
+ * are trusted by default unless {@link PublicConfig.shouldSanitizeHTML} is set to true.
1607
+ */
1608
+ user_type: UserType;
1609
+ /**
1610
+ * A URL pointing to an avatar for the response author. This image should be a square.
1611
+ */
1612
+ profile_picture_url?: string;
1613
+ }
1614
+ /**
1615
+ * A single search result.
1616
+ *
1617
+ * @category Messaging
1618
+ */
1619
+ interface SearchResult {
1620
+ /**
1621
+ * The search result. This can be drilled into and viewed in a larger and scrollable format.
1622
+ */
1623
+ body?: string;
1624
+ }
1625
+
1626
+ /**
1627
+ * Constants for the Carbon FileStatus type because they weren't kind enough to include their own enum.
1628
+ *
1629
+ * @category Service desk
1630
+ */
1631
+ declare enum FileStatusValue {
1632
+ COMPLETE = "complete",
1633
+ EDIT = "edit",
1634
+ UPLOADING = "uploading",
1635
+ SUCCESS = "success"
1636
+ }
1637
+ /**
1638
+ * An interface that represents a file to upload and its current upload status.
1639
+ *
1640
+ * @category Service desk
1641
+ */
1642
+ interface FileUpload {
1643
+ /**
1644
+ * A unique ID for the file.
1645
+ */
1646
+ id: string;
1647
+ /**
1648
+ * The file to upload.
1649
+ */
1650
+ file: File;
1651
+ /**
1652
+ * The current upload status.
1653
+ */
1654
+ status: FileStatusValue;
1655
+ /**
1656
+ * Indicates if the file contains an error or failed to upload.
1657
+ */
1658
+ isError?: boolean;
1659
+ /**
1660
+ * If the file failed to upload, this is an optional error message to display.
1661
+ */
1662
+ errorMessage?: string;
1663
+ }
1664
+ /**
1665
+ * The section of the public config that contains configuration options for service desk integrations.
1666
+ *
1667
+ * @category Service desk
1668
+ */
1669
+ interface ServiceDeskPublicConfig {
1670
+ /**
1671
+ * The timeout value in seconds to use when determining agent availability. When a connect_to_agent response is
1672
+ * received, the system will ask the service desk if any agents are available. If no response is received within
1673
+ * the timeout window, the system will return "false" to indicate no agents are available.
1674
+ */
1675
+ availabilityTimeoutSeconds?: number;
1676
+ /**
1677
+ * Indicates if Carbon AI Chat should auto-connect to an agent whenever it receives a connect_to_agent response and
1678
+ * agents are available. This essentially mimics the user clicking the "Request agent" button on the card. The
1679
+ * card is still displayed to the user.
1680
+ */
1681
+ skipConnectHumanAgentCard?: boolean;
1682
+ /**
1683
+ * The timeout value is seconds to use when waiting for an agent to join the chat after an agent has been
1684
+ * requested. If no agent joins after this time, the chat will be ended and an error message will be displayed to
1685
+ * the user. By default, there is no timeout.
1686
+ */
1687
+ agentJoinTimeoutSeconds?: number;
1688
+ /**
1689
+ * Indicates if Carbon AI Chat should automatically attempt to reconnect the user to a human agent when it is loaded. This
1690
+ * only works if the service desk integration being used supports reconnecting. This value defaults to true.
1691
+ */
1692
+ allowReconnect?: boolean;
1693
+ }
1694
+ /**
1695
+ * Represents the different states for the availability of a human agent from a service desk.
1696
+ *
1697
+ * @category Service desk
1698
+ */
1699
+ declare enum HumanAgentsOnlineStatus {
1700
+ /**
1701
+ * Indicates that agents are online.
1702
+ */
1703
+ ONLINE = "online",
1704
+ /**
1705
+ * Indicates that no agents are online.
1706
+ */
1707
+ OFFLINE = "offline",
1708
+ /**
1709
+ * Indicates that it is unknown whether any agents are available. This may be because the service desk being used
1710
+ * doesn't support the ability to determine this information.
1711
+ */
1712
+ UNKNOWN = "unknown"
1713
+ }
1714
+ /**
1715
+ * The parameters that are passed to a service desk factory.
1716
+ *
1717
+ * @category Service desk
1718
+ */
1719
+ interface ServiceDeskFactoryParameters {
1720
+ /**
1721
+ * The callback used by the service desk to communicate with the widget.
1722
+ */
1723
+ callback: ServiceDeskCallback;
1724
+ /**
1725
+ * The instance of Carbon AI Chat.
1726
+ */
1727
+ instance: ChatInstance;
1728
+ /**
1729
+ * Any state that was stored for the service desk. This value may be undefined if no state has been stored.
1730
+ */
1731
+ persistedState: unknown;
1732
+ }
1733
+ /**
1734
+ * This interface represents the operations that a service desk integration can call on Carbon AI Chat when it wants web
1735
+ * chat to do something. When a service desk integration instance is created, Carbon AI Chat will provide an
1736
+ * implementation of this interface to the integration for it to use.
1737
+ *
1738
+ * @category Service desk
1739
+ */
1740
+ interface ServiceDeskCallback<TPersistedStateType = unknown> {
1741
+ /**
1742
+ * Updates Carbon AI Chat with the capabilities supported by the service desk. Some of these capabilities may support
1743
+ * being changed dynamically and can be updated at any time.
1744
+ *
1745
+ * @param capabilities The set of capabilities to update. Only properties that need to be changed need to be included.
1746
+ */
1747
+ updateCapabilities(capabilities: Partial<ServiceDeskCapabilities>): void;
1748
+ /**
1749
+ * Sends updated availability information to the chat widget for a user who is waiting to be connected to an
1750
+ * agent (e.g. the user is number 2 in line). This may be called at any point while waiting for the connection to
1751
+ * provide newer information.
1752
+ *
1753
+ * Note: Of the fields in the AgentAvailability object, only one of positionInQueue and estimatedWaitTime can be
1754
+ * rendered in the widget. If both fields are provided, estimatedWaitTime will take priority and the
1755
+ * positionInQueue field will be ignored.
1756
+ *
1757
+ * @param availability The availability information to display to the user.
1758
+ */
1759
+ updateAgentAvailability(availability: AgentAvailability): Promise<void>;
1760
+ /**
1761
+ * Informs the chat widget that an agent has joined the chat.
1762
+ */
1763
+ agentJoined(profile: ResponseUserProfile): Promise<void>;
1764
+ /**
1765
+ * Informs the chat widget that the agent has read all the messages that have been sent to the service desk.
1766
+ */
1767
+ agentReadMessages(): Promise<void>;
1768
+ /**
1769
+ * Tells the chat widget if an agent has started or stopped typing.
1770
+ *
1771
+ * @param isTyping If true, indicates that the agent is typing. False indicates the agent has stopped typing.
1772
+ */
1773
+ agentTyping(isTyping: boolean): Promise<void>;
1774
+ /**
1775
+ * Sends a message to the chat widget from an agent.
1776
+ *
1777
+ * Note: The text response type from the standard Watson API is supported in addition to the Carbon AI Chat specific
1778
+ * MessageResponseTypes.INLINE_ERROR response type.
1779
+ *
1780
+ * @param message The message to display to the user. Note, the ability to pass a string for the message was added in
1781
+ * Carbon AI Chat 6.7.0. Earlier versions of Carbon AI Chat will not work if you pass just a string.
1782
+ * @param agentID The ID of the agent who is sending the message. If this is not provided, then the ID of the last
1783
+ * agent who joined the conversation will be used.
1784
+ */
1785
+ sendMessageToUser(message: MessageResponse | string, agentID?: string): Promise<void>;
1786
+ /**
1787
+ * Informs the chat widget that a transfer to another agent is in progress. The agent profile information is
1788
+ * optional if the service desk doesn't have the information available. This message simply tells the chat widget
1789
+ * that the transfer has started. The service desk should inform the widget when the transfer is complete by
1790
+ * sending a {@link agentJoined} message later.
1791
+ */
1792
+ beginTransferToAnotherAgent(profile?: ResponseUserProfile): Promise<void>;
1793
+ /**
1794
+ * Informs the chat widget that the agent has left the conversation. This does not end the conversation itself,
1795
+ * rather the only action that occurs is the visitor receives the agent left status message. If the user sends
1796
+ * another message, it is up to the service desk to decide what to do with it.
1797
+ */
1798
+ agentLeftChat(): Promise<void>;
1799
+ /**
1800
+ * Informs the chat widget that the agent has ended the conversation.
1801
+ */
1802
+ agentEndedChat(): Promise<void>;
1803
+ /**
1804
+ * Sets the state of the given error type.
1805
+ *
1806
+ * @param errorInfo Details for the error whose state is being set.
1807
+ */
1808
+ setErrorStatus(errorInfo: ServiceDeskErrorInfo): Promise<void>;
1809
+ /**
1810
+ * Updates the status of a file upload. The upload may either be successful or an error may have occurred. The
1811
+ * location of a file upload may be in one of two places. The first occurs when the user has selected a file to be
1812
+ * uploaded but has not yet sent the file. In this case, the file appears inside the Carbon AI Chat input area. If an
1813
+ * error is indicated on the file, the error message will be displayed along with the file and the user must
1814
+ * remove the file from the input area before a message can be sent.
1815
+ *
1816
+ * The second occurs after the user has sent the file and the service desk has begun to upload the file. In this
1817
+ * case, the file no longer appears in the input area but appears as a sent message in the message list. If an
1818
+ * error occurs during this time, an icon will appear next to the message to indicate an error occurred and an
1819
+ * error message will be added to the message list.
1820
+ *
1821
+ * @param fileID The ID of the file upload to update.
1822
+ * @param isError Indicates that the upload has an error or failed to upload.
1823
+ * @param errorMessage An error message to display along with a file in error.
1824
+ */
1825
+ setFileUploadStatus(fileID: string, isError?: boolean, errorMessage?: string): Promise<void>;
1826
+ /**
1827
+ * Requests that the user share their screen with the agent. This will present a modal dialog to the user who must
1828
+ * respond before continuing the conversation. This method returns a Promise that resolves when the user has
1829
+ * responded to the request or the request times out.
1830
+ *
1831
+ * @returns Returns a Promise that will resolve with the state the of the request. This Promise will reject if no
1832
+ * chat with an agent is currently running.
1833
+ */
1834
+ screenShareRequest(): Promise<ScreenShareState>;
1835
+ /**
1836
+ * Informs Carbon AI Chat that a screen sharing session has ended or been cancelled. This may occur while waiting for a
1837
+ * screen sharing request to be accepted or while screen sharing is in progress.
1838
+ */
1839
+ screenShareEnded(): Promise<void>;
1840
+ /**
1841
+ * Returns the persisted agent state from the store. This is the current state as updated by
1842
+ * {@link updatePersistedState}. The object returned here is frozen and may not be modified.
1843
+ */
1844
+ persistedState(): TPersistedStateType;
1845
+ /**
1846
+ * Allows the service desk to store state that may be retrieved when Carbon AI Chat is reloaded on a page. This information
1847
+ * is stored in browser session storage which has a total limit of 5MB per origin so the storage should be used
1848
+ * sparingly. Also, the value provided here must be JSON serializable.
1849
+ *
1850
+ * When Carbon AI Chat is reloaded, the data provided here will be returned to the service desk via the
1851
+ * ServiceDeskFactoryParameters.persistedState property. This data may also be retrieved by using the
1852
+ * {@link persistedState} method.
1853
+ *
1854
+ * @param state The state to update.
1855
+ * @param mergeWithCurrent Indicates if the new state should be merged into the existing state. If false, then the
1856
+ * existing state will be fully replaced with the new state. Merging with existing state expects the state to be
1857
+ * an object. This argument is true by default.
1858
+ */
1859
+ updatePersistedState(state: DeepPartial<TPersistedStateType>, mergeWithCurrent?: boolean): void;
1860
+ }
1861
+ /**
1862
+ * The set of capabilities and parameters that are supported by the service desk.
1863
+ *
1864
+ * @category Service desk
1865
+ */
1866
+ type ServiceDeskCapabilities = FileUploadCapabilities;
1867
+ /**
1868
+ * The possible state changes for a screen sharing request.
1869
+ *
1870
+ * @category Service desk
1871
+ */
1872
+ declare enum ScreenShareState {
1873
+ /**
1874
+ * Indicates the screen sharing was accepted by the user.
1875
+ */
1876
+ ACCEPTED = "accepted",
1877
+ /**
1878
+ * Indicates the screen sharing was declined by the user.
1879
+ */
1880
+ DECLINED = "declined",
1881
+ /**
1882
+ * Indicates the screen sharing request was cancelled.
1883
+ */
1884
+ CANCELLED = "cancelled",
1885
+ /**
1886
+ * Indicates that screen sharing has ended.
1887
+ */
1888
+ ENDED = "ended"
1889
+ }
1890
+ /**
1891
+ * Information about the current availability of an agent while a user is waiting to be connected. If these are not set
1892
+ * the Carbon AI Chat will provide generic messaging letting the user know that a request for an agent has been sent.
1893
+ *
1894
+ * Note that only one of these fields will be used by Carbon AI Chat if more than one has been assigned a value. Priority
1895
+ * first goes to estimatedWaitTime, then positionInQueue, and then message.
1896
+ *
1897
+ * @category Service desk
1898
+ */
1899
+ interface AgentAvailability {
1900
+ /**
1901
+ * The current position of the user in a queue. E.g. "You are number 2 in line."
1902
+ */
1903
+ positionInQueue?: number;
1904
+ /**
1905
+ * The estimated wait time for the user in minutes. E.g. "Current wait time is 2 minutes."
1906
+ */
1907
+ estimatedWaitTime?: number;
1908
+ /**
1909
+ * A custom message to display to the user containing the updated status. This may contain markdown.
1910
+ */
1911
+ message?: string;
1912
+ }
1913
+ /**
1914
+ * The possible events that may have some form of error status.
1915
+ *
1916
+ * @category Service desk
1917
+ */
1918
+ declare enum ErrorType {
1919
+ /**
1920
+ * This error is meant to be displayed while the user is attempting to connect to a service desk and before an
1921
+ * agent has joined. If this error is generated by the service desk, it is expected that the service desk will
1922
+ * treat the chat as having ended (or never started).
1923
+ */
1924
+ CONNECTING = 1,
1925
+ /**
1926
+ * This is used to indicate the state of errors that can happen any time during a chat where the service desk
1927
+ * implementation has lost a connection to the back-end. If this error occurs while the user is waiting for an
1928
+ * agent to join, it will be treated as a {@link ErrorType.CONNECTING} error instead.
1929
+ */
1930
+ DISCONNECTED = 2,
1931
+ /**
1932
+ * This error is used to report when there was an error sending a message to the agent.
1933
+ */
1934
+ USER_MESSAGE = 3
1935
+ }
1936
+ /**
1937
+ * This is the parent interface for the information passed to {@link ServiceDeskCallback#setErrorStatus}. It is used
1938
+ * as a discriminating union where the {@link #type} property is the discriminating value that determines which
1939
+ * child interface is to be used.
1940
+ *
1941
+ * @category Service desk
1942
+ */
1943
+ interface BaseErrorInfo {
1944
+ /**
1945
+ * An optional value that will be logged to the console as an error.
1946
+ */
1947
+ logInfo?: unknown;
1948
+ }
1949
+ /**
1950
+ * This error is meant to be displayed while the user is attempting to connect to a service desk and before an
1951
+ * agent has joined. If this error is generated by the service desk, it is expected that the service desk will
1952
+ * treat the chat as having ended (or never started).
1953
+ *
1954
+ * @category Service desk
1955
+ */
1956
+ interface ConnectingErrorInfo extends BaseErrorInfo {
1957
+ /**
1958
+ * The discriminating value for this type.
1959
+ */
1960
+ type: ErrorType.CONNECTING;
1961
+ /**
1962
+ * An optional message that is displayed to the user in the assistant view. If this value is not provided, a default
1963
+ * message will be shown instead.
1964
+ *
1965
+ * Note that support for this field was added in Carbon AI Chat 6.7.0. It will be ignored in earlier versions.
1966
+ */
1967
+ messageToUser?: string;
1968
+ }
1969
+ /**
1970
+ * This is used to indicate the state of errors that can happen any time during a chat where the service desk
1971
+ * implementation has lost a connection to the back-end. If this error occurs while the user is waiting for an
1972
+ * agent to join, it will be treated as a {@link ErrorType.CONNECTING} error instead.
1973
+ *
1974
+ * @category Service desk
1975
+ */
1976
+ interface DisconnectedErrorInfo extends BaseErrorInfo {
1977
+ /**
1978
+ * The discriminating value for this type.
1979
+ */
1980
+ type: ErrorType.DISCONNECTED;
1981
+ /**
1982
+ * Indicates if the service desk has become disconnected. A value of true can be passed that will indicate that a
1983
+ * previous disconnection is over and the service desk is now connected again.
1984
+ */
1985
+ isDisconnected: boolean;
1986
+ }
1987
+ /**
1988
+ * This error is used to report when there was an error sending a message to the agent.
1989
+ *
1990
+ * @category Service desk
1991
+ */
1992
+ interface UserMessageErrorInfo extends BaseErrorInfo {
1993
+ /**
1994
+ * The discriminating value for this type.
1995
+ */
1996
+ type: ErrorType.USER_MESSAGE;
1997
+ /**
1998
+ * The ID of the message that is in error.
1999
+ */
2000
+ messageID: string;
2001
+ }
2002
+ /**
2003
+ * The type for the information passed to {@link ServiceDeskCallback#setErrorStatus}. It is a discriminating union
2004
+ * where the type property is the discriminating value that determines which child interface is to be used.
2005
+ *
2006
+ * @category Service desk
2007
+ */
2008
+ type ServiceDeskErrorInfo = ConnectingErrorInfo | DisconnectedErrorInfo | UserMessageErrorInfo;
2009
+ /**
2010
+ * Additional options that may be passed to the service desk when a chat is started.
2011
+ *
2012
+ * @category Service desk
2013
+ */
2014
+ interface StartChatOptions<TPayloadType = unknown> {
2015
+ /**
2016
+ * Some arbitrary payload of data that was provided as part of the "human_agent:pre:startChat" event.
2017
+ */
2018
+ preStartChatPayload: TPayloadType;
2019
+ }
2020
+ /**
2021
+ * Additional info that may be provided when a chat is ended.
2022
+ *
2023
+ * @category Service desk
2024
+ */
2025
+ interface EndChatInfo<TPayloadType = unknown> {
2026
+ /**
2027
+ * Before a chat is ended, a {@link BusEventType.HUMAN_AGENT_PRE_END_CHAT} is fired. The payload value assigned to this
2028
+ * event by a listener is provided here.
2029
+ */
2030
+ preEndChatPayload: TPayloadType;
2031
+ /**
2032
+ * Indicates if the chat was ended by the agent (or by the service desk integration). If false, indicates the chat
2033
+ * was ended by the user or by Carbon AI Chat.
2034
+ */
2035
+ endedByHumanAgent: boolean;
2036
+ }
2037
+ /**
2038
+ * This is a set of additional data that may be included when the user sends a message to an agent.
2039
+ *
2040
+ * @category Service desk
2041
+ */
2042
+ interface AdditionalDataToAgent {
2043
+ /**
2044
+ * A set of files that user has selected to upload to an agent. This value may be undefined if there are no files
2045
+ * to upload.
2046
+ */
2047
+ filesToUpload?: FileUpload[];
2048
+ }
2049
+ /**
2050
+ * This is the public interface for a human agent service desk integration. This is the interface between the chat
2051
+ * widget and the implementation of the human agent interface with one of the various supported service desks.
2052
+ *
2053
+ * @category Service desk
2054
+ */
2055
+ interface ServiceDesk {
2056
+ /**
2057
+ * Returns a name for this service desk integration. This value should reflect the service desk that is being
2058
+ * integrated to (e.g. "genesys web messenger"). This information will be reported to IBM and may be used to gauge
2059
+ * interest in various service desks for the possibility of creating fully supported out-of-the-box implementations.
2060
+ *
2061
+ * This value is required for custom service desks and may have a maximum of 40 characters.
2062
+ */
2063
+ getName?: () => string;
2064
+ /**
2065
+ * Instructs the service desk to start a new chat. This will be called when a user requests to connect to an agent
2066
+ * and Carbon AI Chat initiates the process (typically when the user clicks the button on the "Connect to Agent" card).
2067
+ * It will make the appropriate calls to the service desk to start the chat and will make use of the callback to
2068
+ * inform Carbon AI Chat when an agent joins or messages are received.
2069
+ *
2070
+ * This may be called multiple times by Carbon AI Chat. If a user begins a chat with an agent, ends the chat and then
2071
+ * begins a new chat with an agent, this function will be called again.
2072
+ *
2073
+ * If the integration is unable to start a chat (such as if the service desk is down or no agents are available)
2074
+ * then this function should throw an error to let Carbon AI Chat know that the chat could not be started.
2075
+ *
2076
+ * The {@link areAnyAgentsOnline} function is called before this function is called and is called as soon as a
2077
+ * "connect_to_agent" message has been received from the assistant. This determines if the "Connect to Agent" card
2078
+ * should be displayed to the user or if the "no agents are available" message configured in the skill should be
2079
+ * shown instead.
2080
+ *
2081
+ * @param connectMessage The original server message response that caused the connection to an agent. It will
2082
+ * contain specific information to send to the service desk as part of the connection. This can include things
2083
+ * like a message to display to a human agent.
2084
+ * @param startChatOptions Additional configuration for startChat.
2085
+ * @returns Returns a Promise that resolves when the service desk has successfully started a new chat. This does
2086
+ * not necessarily mean that an agent has joined the conversation or has read any messages sent by the user.
2087
+ */
2088
+ startChat: (connectMessage: MessageResponse, startChatOptions: StartChatOptions) => Promise<void>;
2089
+ /**
2090
+ * Tells the service desk to terminate the chat.
2091
+ *
2092
+ * @param info Additional info that may be provided as part of ending the chat.
2093
+ * @returns Returns a Promise that resolves when the service desk has successfully handled the call.
2094
+ */
2095
+ endChat: (info: EndChatInfo<unknown>) => Promise<void>;
2096
+ /**
2097
+ * Sends a message to the agent in the service desk. Note that the message text may be empty if the user has
2098
+ * selected files to upload and has not chosen to include a message to go along with the files.
2099
+ *
2100
+ * @param message The message from the user.
2101
+ * @param messageID The unique ID of the message assigned by the widget.
2102
+ * @param additionalData Additional data to include in the message to the agent.
2103
+ * @returns Returns a Promise that resolves when the service desk has successfully handled the call.
2104
+ */
2105
+ sendMessageToAgent: (message: MessageRequest, messageID: string, additionalData: AdditionalDataToAgent) => Promise<void>;
2106
+ /**
2107
+ * Tells the service desk if a user has started or stopped typing.
2108
+ *
2109
+ * @param isTyping If true, indicates that the user is typing. False indicates the user has stopped typing.
2110
+ * @returns Returns a Promise that resolves when the service desk has successfully handled the call.
2111
+ * @since 5.1.1
2112
+ */
2113
+ userTyping?: (isTyping: boolean) => Promise<void>;
2114
+ /**
2115
+ * Informs the service desk that the user has read all the messages that have been sent by the service desk.
2116
+ *
2117
+ * @returns Returns a Promise that resolves when the service desk has successfully handled the call.
2118
+ */
2119
+ userReadMessages?: () => Promise<void>;
2120
+ /**
2121
+ * Checks if any agents are online and can connect to a user when they become available. This does not necessarily
2122
+ * mean that an agent is immediately available; when a chat is started, the user may still have to wait for an
2123
+ * agent to become available. The callback function {@link ServiceDeskCallback.updateAgentAvailability} is used to
2124
+ * give the user more up-to-date information while they are waiting for an agent to become available.
2125
+ *
2126
+ * @param connectMessage The message that contains the transfer_info object that may be used by the service desk,
2127
+ * so it can perform a more specific check.
2128
+ * @returns True if some agents are available or false if no agents are available. This may also return null which
2129
+ * means the availability status of agents is unknown or the service desk doesn't support this information.
2130
+ */
2131
+ areAnyAgentsOnline?: (connectMessage: MessageResponse) => Promise<boolean | null>;
2132
+ /**
2133
+ * Indicates that the user has selected some files to be uploaded but that the user has not yet chosen to send
2134
+ * them to the agent. This method can use this as an opportunity to perform any early validation of the files in
2135
+ * order to display an error to the user. It should not actually upload the files at this point. If the user
2136
+ * chooses to send the files to the agent, they will be included later when {@link ServiceDesk#sendMessageToAgent} is called.
2137
+ *
2138
+ * This method may be called multiple times before a user sends the files.
2139
+ *
2140
+ * If there are errors in the files, this method should use {@link ServiceDeskCallback#setFileUploadStatus} to update
2141
+ * the status with an error message. The user will not be able to upload any files until any files in error are
2142
+ * removed.
2143
+ */
2144
+ filesSelectedForUpload?: (uploads: FileUpload[]) => void;
2145
+ /**
2146
+ * Tells the service desk that the user has requested to stop sharing their screen.
2147
+ */
2148
+ screenShareStop?: () => Promise<void>;
2149
+ /**
2150
+ * This will be called when the service desk is first initialized and it is determined that the user was previously
2151
+ * connected to an agent. This function should perform whatever steps are necessary to reconnect the user. Web chat
2152
+ * will assume the user is permitted to send messages and is connected to the same agent when this function resolves.
2153
+ *
2154
+ * @returns true to indicate that the reconnect was successful.
2155
+ */
2156
+ reconnect?: () => Promise<boolean>;
2157
+ }
2158
+
2159
+ /**
2160
+ * This file contains the type definitions for the event bus.
2161
+ */
2162
+
2163
+ /** @category Events */
2164
+ declare enum BusEventType {
2165
+ /**
2166
+ * When a panel has been closed.
2167
+ */
2168
+ CLOSE_PANEL_BUTTON_TOGGLED = "closePanelButton:toggled",
2169
+ /**
2170
+ * Fired before a message is received. Can take mutations to the message.
2171
+ */
2172
+ PRE_RECEIVE = "pre:receive",
2173
+ /**
2174
+ * Fired after a message is received.
2175
+ */
2176
+ RECEIVE = "receive",
2177
+ /**
2178
+ * Fired before a message is sent to customSendMessage. Can take mutations to the message.
2179
+ */
2180
+ PRE_SEND = "pre:send",
2181
+ /**
2182
+ * Fired after the message is sent to customSendMessage.
2183
+ */
2184
+ SEND = "send",
2185
+ /**
2186
+ * Fired before the view changes (e.g. when the chat window closes).
2187
+ */
2188
+ VIEW_PRE_CHANGE = "view:pre:change",
2189
+ /**
2190
+ * Fired after the view changes (e.g. when the chat window closes).
2191
+ */
2192
+ VIEW_CHANGE = "view:change",
2193
+ MESSAGE_ITEM_CUSTOM = "messageItemCustom",
2194
+ /**
2195
+ * Fired when a userDefined message is received.
2196
+ */
2197
+ USER_DEFINED_RESPONSE = "userDefinedResponse",
2198
+ /**
2199
+ * Fired when history begins to load.
2200
+ */
2201
+ HISTORY_BEGIN = "history:begin",
2202
+ /**
2203
+ * Fired after history is loaded.
2204
+ */
2205
+ HISTORY_END = "history:end",
2206
+ /**
2207
+ * Fired before a conversation restarts.
2208
+ */
2209
+ PRE_RESTART_CONVERSATION = "pre:restartConversation",
2210
+ /**
2211
+ * Fired after a conversation restarts.
2212
+ */
2213
+ RESTART_CONVERSATION = "restartConversation",
2214
+ /**
2215
+ * When the chat has finished hydrating from history or welcome node request.
2216
+ */
2217
+ CHAT_READY = "chat:ready",
2218
+ /**
2219
+ * Fired before a custom panel opens.
2220
+ */
2221
+ CUSTOM_PANEL_PRE_OPEN = "customPanel:pre:open",
2222
+ /**
2223
+ * Fired after a custom panel opens.
2224
+ */
2225
+ CUSTOM_PANEL_OPEN = "customPanel:open",
2226
+ /**
2227
+ * Fired before a custom panel closes.
2228
+ */
2229
+ CUSTOM_PANEL_PRE_CLOSE = "customPanel:pre:close",
2230
+ /**
2231
+ * Fired after a custom panel closes.
2232
+ */
2233
+ CUSTOM_PANEL_CLOSE = "customPanel:close",
2234
+ /**
2235
+ * This event is fired before Carbon AI Chat processes a message received from a human agent from a service desk.
2236
+ * You can use this to filter messages before they are displayed to the end user.
2237
+ */
2238
+ HUMAN_AGENT_PRE_RECEIVE = "human_agent:pre:receive",
2239
+ /**
2240
+ * This event is fired after Carbon AI Chat processes a message received from a human agent from a service desk.
2241
+ * You can use this to update your history store.
2242
+ */
2243
+ HUMAN_AGENT_RECEIVE = "human_agent:receive",
2244
+ /**
2245
+ * This event is fired before Carbon AI Chat sends a message to a human agent from a service desk.
2246
+ * You can use this to filter messages before they are sent to the agent.
2247
+ */
2248
+ HUMAN_AGENT_PRE_SEND = "human_agent:pre:send",
2249
+ /**
2250
+ * This event is fired after Carbon AI Chat sends a message to a human agent from a service desk.
2251
+ * You can use this to update your history store.
2252
+ */
2253
+ HUMAN_AGENT_SEND = "human_agent:send",
2254
+ /**
2255
+ * This event is fired before a chat with a service desk has started. This occurs as soon as the user clicks the
2256
+ * "Request agent" button and before any attempt is made to communicate with the service desk.
2257
+ */
2258
+ HUMAN_AGENT_PRE_START_CHAT = "human_agent:pre:startChat",
2259
+ /**
2260
+ * This event is fired before a chat with an agent is ended. This occurs after the user has selected "Yes" from the
2261
+ * confirmation modal but it can also be fired if the chat is ended by the agent. Note that this is not fired if a
2262
+ * request for an agent is cancelled. The human_agent:endChat event however is fired in that case.
2263
+ */
2264
+ HUMAN_AGENT_PRE_END_CHAT = "human_agent:pre:endChat",
2265
+ /**
2266
+ * This event is fired after a chat with an agent has ended. This is fired after {@link BusEventType.HUMAN_AGENT_PRE_END_CHAT} but
2267
+ * can be fired both from the user leaving the chat or the agent ending the chat.
2268
+ */
2269
+ HUMAN_AGENT_END_CHAT = "human_agent:endChat",
2270
+ /**
2271
+ * This event is fired after Carbon AI Chat calls "areAnyAgentsOnline" for a service desk. It will report the value returned
2272
+ * from that call. This is particularly useful if some custom code wants to take action if no agents are online.
2273
+ */
2274
+ HUMAN_AGENT_ARE_ANY_AGENTS_ONLINE = "human_agent:areAnyAgentsOnline",
2275
+ /**
2276
+ * Fired when a new chunk in a user_defined response comes through.
2277
+ */
2278
+ CHUNK_USER_DEFINED_RESPONSE = "chunk:userDefinedResponse",
2279
+ /**
2280
+ * This event is fired when the user interacts with the feedback controls on a message. This includes both the feedback
2281
+ * buttons (thumbs up/down) as well as the details popup where the user can submit additional information.
2282
+ */
2283
+ FEEDBACK = "feedback",
2284
+ /**
2285
+ * This event is fired when the "stop streaming" button in the input field is clicked.
2286
+ */
2287
+ STOP_STREAMING = "stopStreaming",
2288
+ /**
2289
+ * This event is fired whenever the public state returned by ChatInstance.getState() changes.
2290
+ * This includes changes to viewState, showUnreadIndicator, and other persisted state.
2291
+ */
2292
+ STATE_CHANGE = "state:change",
2293
+ /**
2294
+ * Fired if the disclaimer is accepted.
2295
+ */
2296
+ DISCLAIMER_ACCEPTED = "disclaimerAccepted"
2297
+ }
2298
+ /**
2299
+ * The possible reasons why the view may be changed.
2300
+ *
2301
+ * @category Events
2302
+ */
2303
+ declare enum ViewChangeReason {
2304
+ /**
2305
+ * Indicates the Carbon AI Chat has loaded for the first time and a view is trying to open. If openChatByDefault is
2306
+ * true then the main window will be trying to open, otherwise the launcher will be trying to open.
2307
+ */
2308
+ WEB_CHAT_LOADED = "webChatLoaded",
2309
+ /**
2310
+ * Indicates the user clicked on our built-in launcher button that opened the main window.
2311
+ */
2312
+ LAUNCHER_CLICKED = "launcherClicked",
2313
+ /**
2314
+ * Indicates the user clicked on our built-in minimize button that closed the launcher.
2315
+ */
2316
+ MAIN_WINDOW_MINIMIZED = "mainWindowMinimized",
2317
+ /**
2318
+ * Indicates the user clicked the close and restart button that minimized to the launcher.
2319
+ */
2320
+ MAIN_WINDOW_CLOSED_AND_RESTARTED = "mainWindowClosedAndRestarted",
2321
+ /**
2322
+ * Indicates the view was changed by a call to {@link ChatInstance.changeView}.
2323
+ */
2324
+ CALLED_CHANGE_VIEW = "calledChangeView"
2325
+ }
2326
+ /**
2327
+ * The different sources that can cause a send event to occur.
2328
+ *
2329
+ * @category Events
2330
+ */
2331
+ declare enum MessageSendSource {
2332
+ /**
2333
+ * The user has entered a value from the main input on the message list.
2334
+ */
2335
+ MESSAGE_INPUT = "messageInput",
2336
+ /**
2337
+ * The user has entered a value from the input on the home screen.
2338
+ */
2339
+ HOME_SCREEN_INPUT = "homeScreenInput",
2340
+ /**
2341
+ * The user clicked a button from an option response.
2342
+ */
2343
+ OPTION_BUTTON = "optionButton",
2344
+ /**
2345
+ * The user selected a value from a dropdown for an option response.
2346
+ */
2347
+ OPTION_DROP_DOWN = "optionDropDown",
2348
+ /**
2349
+ * The message was sent as an automatic re-send when Carbon AI Chat is loaded. This occurs when Carbon AI Chat sees that the
2350
+ * last message request did not receive a response.
2351
+ */
2352
+ HYDRATE_RESEND = "hydrateResend",
2353
+ /**
2354
+ * The message was sent as an event history update.
2355
+ */
2356
+ HISTORY_UPDATE = "historyUpdate",
2357
+ /**
2358
+ * An external call to the public "instance.send" method was made.
2359
+ */
2360
+ INSTANCE_SEND = "instanceSend",
2361
+ /**
2362
+ * The user chose a value from the date picker.
2363
+ */
2364
+ DATE_PICKER = "datePicker",
2365
+ /**
2366
+ * The user clicked a post back button from a button response.
2367
+ */
2368
+ POST_BACK_BUTTON = "postBackButton",
2369
+ /**
2370
+ * The user clicked a starter from the home screen.
2371
+ */
2372
+ HOME_SCREEN_STARTER = "homeScreenStarter",
2373
+ /**
2374
+ * A default request for the welcome message was made.
2375
+ */
2376
+ WELCOME_REQUEST = "welcomeRequest",
2377
+ /**
2378
+ * This is used for message events.
2379
+ */
2380
+ EVENT = "event",
2381
+ /**
2382
+ * Some other source.
2383
+ */
2384
+ OTHER = "other"
2385
+ }
2386
+ /**
2387
+ * The discriminating union of all the possible bus event types.
2388
+ * @category Events
2389
+ */
2390
+ interface BusEvent {
2391
+ /**
2392
+ * The type of this event.
2393
+ */
2394
+ type: BusEventType;
2395
+ }
2396
+ /**
2397
+ *
2398
+ *
2399
+ * @category Events
2400
+ */
2401
+ interface BusEventClosePanelButtonClicked extends BusEvent {
2402
+ type: BusEventType.CLOSE_PANEL_BUTTON_TOGGLED;
2403
+ }
2404
+ /**
2405
+ * @category Events
2406
+ */
2407
+ interface BusEventPreReceive extends BusEvent {
2408
+ type: BusEventType.PRE_RECEIVE;
2409
+ data: MessageResponse;
2410
+ }
2411
+ /**
2412
+ * @category Events
2413
+ */
2414
+ interface BusEventReceive extends BusEvent {
2415
+ type: BusEventType.RECEIVE;
2416
+ data: MessageResponse;
2417
+ }
2418
+ /**
2419
+ * @category Events
2420
+ */
2421
+ interface BusEventPreSend extends BusEvent {
2422
+ type: BusEventType.PRE_SEND;
2423
+ data: MessageRequest;
2424
+ /**
2425
+ * The source of the message being sent.
2426
+ */
2427
+ source: MessageSendSource;
2428
+ }
2429
+ /**
2430
+ * @category Events
2431
+ */
2432
+ interface BusEventSend extends BusEvent {
2433
+ type: BusEventType.SEND;
2434
+ data: MessageRequest;
2435
+ /**
2436
+ * The source of the message being sent.
2437
+ */
2438
+ source: MessageSendSource;
2439
+ }
2440
+ /**
2441
+ * @category Service desk
2442
+ */
2443
+ interface BusEventHumanAgentPreReceive extends BusEvent {
2444
+ type: BusEventType.HUMAN_AGENT_PRE_RECEIVE;
2445
+ data: MessageResponse;
2446
+ responseUserProfile?: ResponseUserProfile;
2447
+ }
2448
+ /**
2449
+ * @category Service desk
2450
+ */
2451
+ interface BusEventHumanAgentReceive extends BusEvent {
2452
+ type: BusEventType.HUMAN_AGENT_RECEIVE;
2453
+ data: MessageResponse;
2454
+ responseUserProfile?: ResponseUserProfile;
2455
+ }
2456
+ /**
2457
+ * @category Service desk
2458
+ */
2459
+ interface BusEventHumanAgentPreSend extends BusEvent {
2460
+ type: BusEventType.HUMAN_AGENT_PRE_SEND;
2461
+ data: MessageRequest;
2462
+ files: FileUpload[];
2463
+ }
2464
+ /**
2465
+ * @category Service desk
2466
+ */
2467
+ interface BusEventHumanAgentSend extends BusEvent {
2468
+ type: BusEventType.HUMAN_AGENT_SEND;
2469
+ data: MessageRequest;
2470
+ files: FileUpload[];
2471
+ }
2472
+ /**
2473
+ * Fires before the view state is updated in the store. This event is awaited, making it ideal for async operations like animations.
2474
+ *
2475
+ * **Event Timing:**
2476
+ * 1. VIEW_PRE_CHANGE fires (awaited)
2477
+ * 2. View state is updated in store
2478
+ * 3. VIEW_CHANGE fires (awaited)
2479
+ *
2480
+ * **Use cases:**
2481
+ * - Run animations before the view changes
2482
+ * - Modify the new view state before it's applied
2483
+ * - Cancel the view change entirely
2484
+ *
2485
+ * @category Events
2486
+ */
2487
+ interface BusEventViewPreChange extends BusEvent {
2488
+ type: BusEventType.VIEW_PRE_CHANGE;
2489
+ /**
2490
+ * The reason the view is changing.
2491
+ */
2492
+ reason: ViewChangeReason;
2493
+ /**
2494
+ * The previous view state before this event.
2495
+ */
2496
+ oldViewState: ViewState;
2497
+ /**
2498
+ * The new view state that Carbon AI Chat is going to switch to. This new state can be changed by the event handler.
2499
+ */
2500
+ newViewState: ViewState;
2501
+ /**
2502
+ * This is used by the event handler to indicate that the view change should be cancelled and Carbon AI Chat's view should
2503
+ * not be changed.
2504
+ */
2505
+ cancelViewChange: boolean;
2506
+ }
2507
+ /**
2508
+ * Fires after the view state has been updated in the store. This event is awaited, making it ideal for async operations that should happen after the view change.
2509
+ *
2510
+ * **Event Timing:**
2511
+ * 1. VIEW_PRE_CHANGE fires (awaited)
2512
+ * 2. View state is updated in store
2513
+ * 3. VIEW_CHANGE fires (awaited) ← You are here
2514
+ *
2515
+ * **Use cases:**
2516
+ * - React to completed view changes
2517
+ * - Run cleanup or follow-up animations
2518
+ * - Cancel and revert the view change (causes immediate revert without firing events)
2519
+ *
2520
+ * @category Events
2521
+ */
2522
+ interface BusEventViewChange extends BusEvent {
2523
+ type: BusEventType.VIEW_CHANGE;
2524
+ /**
2525
+ * The reason the view is changing.
2526
+ */
2527
+ reason: ViewChangeReason;
2528
+ /**
2529
+ * The previous view state from before the view:pre:change event.
2530
+ */
2531
+ oldViewState: ViewState;
2532
+ /**
2533
+ * The new view state that Carbon AI Chat has switched to. This new state can be changed by the event handler.
2534
+ */
2535
+ newViewState: ViewState;
2536
+ /**
2537
+ * This is used by the event handler to indicate that the view change should be cancelled and Carbon AI Chat's view should
2538
+ * not be changed. Since the view has already changed when this event is fired, this property will cause the view to
2539
+ * change back. Note that the view change events are *not* fired when the view changes back.
2540
+ */
2541
+ cancelViewChange: boolean;
2542
+ }
2543
+ /**
2544
+ * @category Events
2545
+ */
2546
+ interface BusEventReset extends BusEvent {
2547
+ type: BusEventType.RESTART_CONVERSATION;
2548
+ }
2549
+ /**
2550
+ * @category Events
2551
+ */
2552
+ interface BusEventChatReady extends BusEvent {
2553
+ type: BusEventType.CHAT_READY;
2554
+ }
2555
+ /**
2556
+ * @category Events
2557
+ */
2558
+ interface BusEventPreReset extends BusEvent {
2559
+ type: BusEventType.PRE_RESTART_CONVERSATION;
2560
+ }
2561
+ /**
2562
+ * This describes a custom event that can be authored with the button response type of type "option". When clicked,
2563
+ * this event will fire and provide information authored in the custom event.
2564
+ *
2565
+ * @category Events
2566
+ */
2567
+ interface BusEventMessageItemCustom extends BusEvent {
2568
+ type: BusEventType.MESSAGE_ITEM_CUSTOM;
2569
+ /**
2570
+ * The button item that triggered this custom event.
2571
+ */
2572
+ messageItem: ButtonItem;
2573
+ /**
2574
+ * The full message response that contained the button item that triggered this custom event.
2575
+ */
2576
+ fullMessage: MessageResponse;
2577
+ }
2578
+ /**
2579
+ * Used to populate user_defined responses. Please see the React or web component documentation as usage of this
2580
+ * differs based on implementation.
2581
+ *
2582
+ * @category Events
2583
+ */
2584
+ interface BusEventUserDefinedResponse extends BusEvent {
2585
+ type: BusEventType.USER_DEFINED_RESPONSE;
2586
+ data: {
2587
+ /**
2588
+ * The individual message item that is being displayed in this custom response.
2589
+ */
2590
+ message: GenericItem;
2591
+ /**
2592
+ * The full message (response or request) that contains the message item.
2593
+ */
2594
+ fullMessage: Message;
2595
+ /**
2596
+ * The slot name for users of the web components cds-aichat-container or cds-aichat-custom-element.
2597
+ */
2598
+ slot?: string;
2599
+ };
2600
+ }
2601
+ /**
2602
+ * @category Events
2603
+ */
2604
+ interface BusEventChunkUserDefinedResponse extends BusEvent {
2605
+ type: BusEventType.CHUNK_USER_DEFINED_RESPONSE;
2606
+ data: {
2607
+ /**
2608
+ * The individual message item that is being displayed in this custom response.
2609
+ */
2610
+ messageItem: DeepPartial<GenericItem>;
2611
+ /**
2612
+ * The full chunk that contained the user defined response.
2613
+ */
2614
+ chunk: PartialOrCompleteItemChunk;
2615
+ /**
2616
+ * The slot name for users of the web components cds-aichat-container or cds-aichat-custom-element.
2617
+ */
2618
+ slot?: string;
2619
+ };
2620
+ }
2621
+ /**
2622
+ * The event is fired whenever the widget begins processing a list of messages that have been loaded from history.
2623
+ * This event may be fired not only when the history is first loaded but it may be fired later during the life of
2624
+ * the widget if additional messages are loaded from history.
2625
+ *
2626
+ * This event is fired when this process begins. This is fired before all the "pre:receive" and "receive" events are
2627
+ * fired which means that the messages here are the original messages before any possible modifications by the event
2628
+ * handlers.
2629
+ *
2630
+ * @category Events
2631
+ */
2632
+ interface BusEventHistoryBegin extends BusEvent {
2633
+ /**
2634
+ * The discriminating type of this event.
2635
+ */
2636
+ type: BusEventType.HISTORY_BEGIN;
2637
+ /**
2638
+ * The list of all the messages that are being loaded by this history event.
2639
+ */
2640
+ messages: Message[];
2641
+ /**
2642
+ * Indicates that modifications were made to the given messages and that updates to those messages should be saved in
2643
+ * the history store. This is similar to the update behavior of the "pre:receive" event that is handled
2644
+ * automatically.
2645
+ */
2646
+ updateMessageIDs?: string[];
2647
+ }
2648
+ /**
2649
+ * The event is fired whenever the widget begins processing a list of messages that have been loaded from history.
2650
+ * This event may be fired not only when the history is first loaded but it may be fired later during the life of
2651
+ * the widget if additional messages are loaded from history.
2652
+ *
2653
+ * This event is fired when this process ends. This is fired after all the "pre:receive" and "receive" events are
2654
+ * fired which means that the messages here are the potentially modified messages after any possible modifications
2655
+ * by the event handlers.
2656
+ *
2657
+ * @category Events
2658
+ */
2659
+ interface BusEventHistoryEnd extends BusEvent {
2660
+ /**
2661
+ * The discriminating type of this event.
2662
+ */
2663
+ type: BusEventType.HISTORY_END;
2664
+ /**
2665
+ * The list of all the messages that were loaded by this history event.
2666
+ */
2667
+ messages: Message[];
2668
+ }
2669
+ /**
2670
+ * @category Events
2671
+ */
2672
+ interface BusEventCustomPanelPreOpen extends BusEvent {
2673
+ type: BusEventType.CUSTOM_PANEL_PRE_OPEN;
2674
+ }
2675
+ /**
2676
+ * @category Events
2677
+ */
2678
+ interface BusEventCustomPanelOpen extends BusEvent {
2679
+ type: BusEventType.CUSTOM_PANEL_OPEN;
2680
+ }
2681
+ /**
2682
+ * @category Events
2683
+ */
2684
+ interface BusEventCustomPanelPreClose extends BusEvent {
2685
+ type: BusEventType.CUSTOM_PANEL_PRE_CLOSE;
2686
+ }
2687
+ /**
2688
+ * @category Events
2689
+ */
2690
+ interface BusEventCustomPanelClose extends BusEvent {
2691
+ type: BusEventType.CUSTOM_PANEL_CLOSE;
2692
+ }
2693
+ /**
2694
+ * This event is fired before the user is connected to a service desk. This occurs as soon as the user clicks the
2695
+ * "Request agent" button and before any attempt is made to communicate with the service desk.
2696
+ *
2697
+ * @category Service desk
2698
+ */
2699
+ interface BusEventHumanAgentPreStartChat<TPayloadType = unknown> extends BusEvent {
2700
+ /**
2701
+ * The type of the event.
2702
+ */
2703
+ type: BusEventType.HUMAN_AGENT_PRE_START_CHAT;
2704
+ /**
2705
+ * The message that was used to trigger the connection to the agent.
2706
+ */
2707
+ message: MessageResponse;
2708
+ /**
2709
+ * This flag can be set by a listener to indicate that the connection process should be cancelled.
2710
+ */
2711
+ cancelStartChat?: boolean;
2712
+ /**
2713
+ * Some arbitrary payload of data that will be passed to the service desk when a chat is started.
2714
+ */
2715
+ preStartChatPayload?: TPayloadType;
2716
+ }
2717
+ /**
2718
+ * This event is fired before a chat with an agent is ended. This occurs after the user has selected "Yes" from the
2719
+ * confirmation modal but it can also be fired if the chat is ended by the agent.
2720
+ *
2721
+ * @category Service desk
2722
+ */
2723
+ interface BusEventHumanAgentPreEndChat<TPayloadType = unknown> extends BusEvent {
2724
+ /**
2725
+ * The type of the event.
2726
+ */
2727
+ type: BusEventType.HUMAN_AGENT_PRE_END_CHAT;
2728
+ /**
2729
+ * Indicates if the chat was ended by the agent.
2730
+ */
2731
+ endedByHumanAgent: boolean;
2732
+ /**
2733
+ * An arbitrary payload object that a listener may set. This payload will be passed to the service desk
2734
+ * ServiceDesk endChat function.
2735
+ */
2736
+ preEndChatPayload: TPayloadType;
2737
+ /**
2738
+ * This value may be set by a listener to indicate that the process of ending the chat should be cancelled.
2739
+ */
2740
+ cancelEndChat: boolean;
2741
+ }
2742
+ /**
2743
+ * This event is fired after a chat with an agent has ended. This is fired after {@link BusEventType.HUMAN_AGENT_PRE_END_CHAT} but
2744
+ * can be fired both from the user leaving the chat or the agent ending the chat.
2745
+ *
2746
+ * @category Service desk
2747
+ */
2748
+ interface BusEventHumanAgentEndChat extends BusEvent {
2749
+ /**
2750
+ * The type of the event.
2751
+ */
2752
+ type: BusEventType.HUMAN_AGENT_END_CHAT;
2753
+ /**
2754
+ * Indicates if the chat was ended by the agent.
2755
+ */
2756
+ endedByHumanAgent: boolean;
2757
+ /**
2758
+ * Indicates if the chat was ended because the request for an agent was cancelled or an error occurred while
2759
+ * starting the chat. This means the start never fully started.
2760
+ */
2761
+ requestCancelled: boolean;
2762
+ }
2763
+ /**
2764
+ * This event is fired after Carbon AI Chat calls "areAnyAgentsOnline" for a service desk. It will report the value returned
2765
+ * from that call. This is particularly useful if some custom code wants to take action if no agents are online.
2766
+ *
2767
+ * @category Service desk
2768
+ */
2769
+ interface BusEventHumanAgentAreAnyAgentsOnline extends BusEvent {
2770
+ /**
2771
+ * The type of the event.
2772
+ */
2773
+ type: BusEventType.HUMAN_AGENT_ARE_ANY_AGENTS_ONLINE;
2774
+ /**
2775
+ * The result that was returned from "areAnyAgentsOnline". If an error occurred, this will be
2776
+ * {@link HumanAgentsOnlineStatus.OFFLINE}.
2777
+ */
2778
+ areAnyAgentsOnline: HumanAgentsOnlineStatus;
2779
+ }
2780
+ /**
2781
+ * The ways the user may interact with the feedback controls.
2782
+ *
2783
+ * @category Events
2784
+ */
2785
+ declare enum FeedbackInteractionType {
2786
+ /**
2787
+ * Indicates the details popup was opened after the user clicked one of the feedback buttons.
2788
+ */
2789
+ DETAILS_OPENED = "detailsOpened",
2790
+ /**
2791
+ * Indicates the details popup was closed after the user clicked the "X" button to close it or if the user clicked the
2792
+ * feedback button that opened it.
2793
+ */
2794
+ DETAILS_CLOSED = "detailsClosed",
2795
+ /**
2796
+ * Indicates feedback was submitted. This includes both when the details panel is open and submitted as well as when
2797
+ * the user clicks a feedback button and the details are not shown.
2798
+ */
2799
+ SUBMITTED = "submitted"
2800
+ }
2801
+ /**
2802
+ * This event is fired when the user interacts with the feedback controls on a message. This includes both the feedback
2803
+ * buttons (thumbs up/down) as well as the details popup where the user can submit additional information.
2804
+ *
2805
+ * @category Events
2806
+ */
2807
+ interface BusEventFeedback extends BusEvent {
2808
+ /**
2809
+ * The message item for which feedback was provided.
2810
+ */
2811
+ messageItem: GenericItem;
2812
+ /**
2813
+ * The message for which feedback was provided.
2814
+ */
2815
+ message: MessageResponse;
2816
+ /**
2817
+ * Indicates if the user is providing positive or negative feedback.
2818
+ */
2819
+ isPositive: boolean;
2820
+ /**
2821
+ * The type of interaction the user had with the feedback.
2822
+ */
2823
+ interactionType: FeedbackInteractionType;
2824
+ /**
2825
+ * When submitting feedback details, this is the text the user entered into the text field (if visible).
2826
+ */
2827
+ text?: string;
2828
+ /**
2829
+ * When submitting feedback details, this is the list of categories the user selected (if visible).
2830
+ */
2831
+ categories?: string[];
2832
+ }
2833
+
2834
+ /**
2835
+ * The types here describe the history structure.
2836
+ * This is used currently for session history and is planned to be reused by the history.
2837
+ */
2838
+ /**
2839
+ * A single interaction in the Session History.
2840
+ *
2841
+ * @category Messaging
2842
+ */
2843
+ interface HistoryItem {
2844
+ /**
2845
+ * The message represented by this history item.
2846
+ */
2847
+ message: MessageRequest | MessageResponse;
2848
+ /**
2849
+ * Time this message occurred. ISO Format (e.g. 2020-03-15T08:59:56.952Z).
2850
+ */
2851
+ time: string;
2852
+ }
2853
+
2854
+ /**
2855
+ * Reasons why a message request was cancelled via the abort signal.
2856
+ *
2857
+ * @category Messaging
2858
+ */
2859
+ declare enum CancellationReason {
2860
+ /**
2861
+ * User clicked the "stop streaming" button during message streaming.
2862
+ */
2863
+ STOP_STREAMING = "Stop streaming",
2864
+ /**
2865
+ * User restarted or cleared the conversation.
2866
+ */
2867
+ CONVERSATION_RESTARTED = "Conversation restarted",
2868
+ /**
2869
+ * Message request exceeded the configured timeout duration.
2870
+ */
2871
+ TIMEOUT = "Request timeout"
2872
+ }
2873
+ /**
2874
+ * Messaging actions for a chat instance.
2875
+ *
2876
+ * @category Messaging
2877
+ */
2878
+ interface ChatInstanceMessaging {
2879
+ /**
2880
+ * Instructs the widget to process the given message as an incoming message received from the assistant. This will
2881
+ * fire a "pre:receive" event immediately and a "receive" event after the event has been processed by the widget.
2882
+ *
2883
+ * @param message A {@link MessageResponse} object.
2884
+ */
2885
+ addMessage: (message: MessageResponse) => Promise<void>;
2886
+ /**
2887
+ * Adds a streaming message chunk to the chat widget.
2888
+ */
2889
+ addMessageChunk: (chunk: StreamChunk) => Promise<void>;
2890
+ /**
2891
+ * Removes the messages with the given IDs from the chat view.
2892
+ */
2893
+ removeMessages: (messageIDs: string[]) => Promise<void>;
2894
+ /**
2895
+ * Clears the current conversation. This will trigger a restart of the conversation but will not start a new
2896
+ * conversation (hydration).
2897
+ */
2898
+ clearConversation: () => Promise<void>;
2899
+ /**
2900
+ * Inserts the given messages into the chat window as part of the chat history. This will fire the history:begin
2901
+ * and history:end events.
2902
+ */
2903
+ insertHistory: (messages: HistoryItem[]) => Promise<void>;
2904
+ /**
2905
+ * Restarts the conversation with the assistant. This does not make any changes to a conversation with a human agent.
2906
+ * This will clear all the current assistant messages from the main assistant view and cancel any outstanding
2907
+ * messages. This will also clear the current assistant session which will force a new session to start on the
2908
+ * next message.
2909
+ */
2910
+ restartConversation: () => Promise<void>;
2911
+ }
2912
+ /**
2913
+ * @category Messaging
2914
+ */
2915
+ interface CustomSendMessageOptions {
2916
+ /**
2917
+ * A signal to let customSendMessage to cancel a request if it has exceeded Carbon AI Chat's timeout.
2918
+ */
2919
+ signal: AbortSignal;
2920
+ /**
2921
+ * If the message was sent with "silent" set to true to not be displayed in the conversation history.
2922
+ */
2923
+ silent: boolean;
2924
+ /**
2925
+ * BusEventSend provides extra context such as MessageSendSource.
2926
+ */
2927
+ busEventSend?: BusEventSend;
2928
+ }
2929
+
2930
+ /**
2931
+ * The subset of HumanAgentState that is persisted to browser storage.
2932
+ *
2933
+ * @category Instance
2934
+ */
2935
+ interface PersistedHumanAgentState {
2936
+ /** Indicates that the user is connected to a human agent. */
2937
+ isConnected: boolean;
2938
+ /** Indicates if the human agent conversation is currently suspended. */
2939
+ isSuspended: boolean;
2940
+ /** The profile of the last human agent to join the chat. */
2941
+ responseUserProfile?: ResponseUserProfile;
2942
+ /** Cache of known agent profiles by ID. */
2943
+ responseUserProfiles: Record<string, ResponseUserProfile>;
2944
+ /** Arbitrary state saved by the service desk. */
2945
+ serviceDeskState?: unknown;
2946
+ }
2947
+
2948
+ /**
2949
+ * The interface represents the API contract with the chat widget and contains all the public methods and properties
2950
+ * that can be used with Carbon AI Chat.
2951
+ *
2952
+ * @category Instance
2953
+ */
2954
+ interface ChatInstance extends EventHandlers, ChatActions {
2955
+ /**
2956
+ * Returns state information of the Carbon AI Chat that could be useful.
2957
+ */
2958
+ getState: () => PublicChatState;
2959
+ /**
2960
+ * Manager for accessing and controlling custom panels.
2961
+ */
2962
+ customPanels?: CustomPanels;
2963
+ }
2964
+ /**
2965
+ * This is the state made available by calling getState. This is a public method that returns immutable values.
2966
+ *
2967
+ * @category Instance
2968
+ */
2969
+ type PublicChatState = Readonly<Omit<PersistedState, "humanAgentState"> & {
2970
+ humanAgent: PublicChatHumanAgentState;
2971
+ }>;
2972
+ /**
2973
+ * Current connection state of the human agent experience.
2974
+ *
2975
+ * @category Instance
2976
+ */
2977
+ type PublicChatHumanAgentState = Readonly<PersistedHumanAgentState & {
2978
+ /** Indicates if Carbon AI Chat is attempting to connect to an agent. */
2979
+ isConnecting: boolean;
2980
+ }>;
2981
+ /**
2982
+ * This is a subset of the public interface that is managed by the event bus that is used for registering and
2983
+ * unregistering event listeners on the bus.
2984
+ *
2985
+ * @category Instance
2986
+ */
2987
+ interface EventHandlers {
2988
+ /**
2989
+ * Adds the given event handler as a listener for events of the given type.
2990
+ *
2991
+ * @param handlers The handler or handlers along with the event type to start listening for events.
2992
+ * @returns The instance for method chaining.
2993
+ */
2994
+ on: (handlers: TypeAndHandler | TypeAndHandler[]) => EventHandlers;
2995
+ /**
2996
+ * Removes an event listener that was previously added via {@link on} or {@link once}.
2997
+ *
2998
+ * @param handlers The handler or handlers along with the event type to stop listening for events.
2999
+ * @returns The instance for method chaining.
3000
+ */
3001
+ off: (handlers: TypeAndHandler | TypeAndHandler[]) => EventHandlers;
3002
+ /**
3003
+ * Adds the given event handler as a listener for events of the given type. After the first event is handled, this
3004
+ * handler will automatically be removed.
3005
+ *
3006
+ * @param handlers The handler or handlers along with the event type to start listening for an event.
3007
+ * @returns The instance for method chaining.
3008
+ */
3009
+ once: (handlers: TypeAndHandler | TypeAndHandler[]) => EventHandlers;
3010
+ }
3011
+ /**
3012
+ * The type of handler for event bus events. This function may return a Promise in which case, the bus will await
3013
+ * the result and the loop will block until the Promise is resolved.
3014
+ *
3015
+ * @category Instance
3016
+ */
3017
+ type EventBusHandler<T extends BusEvent = BusEvent> = (event: T, instance: ChatInstance) => unknown;
3018
+ /**
3019
+ * The type of the object that is passed to the event bus functions (e.g. "on") when registering a handler.
3020
+ *
3021
+ * @category Instance
3022
+ */
3023
+ interface TypeAndHandler {
3024
+ /**
3025
+ * The type of event this handler is for.
3026
+ */
3027
+ type: BusEventType;
3028
+ /**
3029
+ * The handler for events of this type.
3030
+ */
3031
+ handler: EventBusHandler;
3032
+ }
3033
+ /**
3034
+ * This is a subset of the public interface that provides methods that can be used by the user to control the widget
3035
+ * and have it perform certain actions.
3036
+ *
3037
+ * @category Instance
3038
+ */
3039
+ interface ChatActions {
3040
+ /**
3041
+ * Messaging actions for a chat instance.
3042
+ */
3043
+ messaging: ChatInstanceMessaging;
3044
+ /**
3045
+ * This function can be called when another component wishes this component to gain focus. It is up to the
3046
+ * component to decide where focus belongs. This may return true or false to indicate if a suitable focus location
3047
+ * was found.
3048
+ */
3049
+ requestFocus: () => boolean | void;
3050
+ /**
3051
+ * Sends the given message to the assistant on the remote server. This will result in a "pre:send" and "send" event
3052
+ * being fired on the event bus. The returned promise will resolve once a response has received and processed and
3053
+ * both the "pre:receive" and "receive" events have fired. It will reject when too many errors have occurred and
3054
+ * the system gives up retrying.
3055
+ *
3056
+ * @param message The message to send.
3057
+ * @param options Options for the message sent.
3058
+ */
3059
+ send: (message: MessageRequest | string, options?: SendOptions) => Promise<void>;
3060
+ /**
3061
+ * Fire the view:pre:change and view:change events and change the view of the Carbon AI Chat. If a {@link ViewType} is
3062
+ * provided then that view will become visible and the rest will be hidden. If a {@link ViewState} is provided that
3063
+ * includes all of the views then all of the views will be changed accordingly. If a partial {@link ViewState} is
3064
+ * provided then only the views provided will be changed.
3065
+ */
3066
+ changeView: (newView: ViewType | ViewState) => Promise<void>;
3067
+ /**
3068
+ * Returns the list of writable elements.
3069
+ */
3070
+ writeableElements: Partial<WriteableElements>;
3071
+ /**
3072
+ * Sets the input field to be invisible. Helpful for when
3073
+ * you want to force input into a button, etc.
3074
+ */
3075
+ updateInputFieldVisibility: (isVisible: boolean) => void;
3076
+ /**
3077
+ * Changes the state of Carbon AI Chat to allow or disallow input. This includes the input field as well as inputs like
3078
+ * buttons and dropdowns.
3079
+ */
3080
+ updateInputIsDisabled: (isDisabled: boolean) => void;
3081
+ /**
3082
+ * Updates the visibility of the custom unread indicator that appears on the launcher. This indicator appears as a
3083
+ * small empty circle on the launcher. If there are any unread messages from a human agent, this indicator will be
3084
+ * shown with a number regardless of the custom setting of this flag.
3085
+ */
3086
+ updateAssistantUnreadIndicatorVisibility: (isVisible: boolean) => void;
3087
+ /**
3088
+ * Scrolls to the (original) message with the given ID. Since there may be multiple message items in a given
3089
+ * message, this will scroll the first message to the top of the message window.
3090
+ *
3091
+ * @param messageID The (original) message ID to scroll to.
3092
+ * @param animate Whether or not the scroll should be animated. Defaults to true.
3093
+ */
3094
+ scrollToMessage: (messageID: string, animate?: boolean) => void;
3095
+ /**
3096
+ * Restarts the conversation with the assistant. This does not make any changes to a conversation with a human agent.
3097
+ * This will clear all the current assistant messages from the main assistant view and cancel any outstanding
3098
+ * messages. This will also clear the current assistant session which will force a new session to start on the
3099
+ * next message.
3100
+ *
3101
+ * @deprecated Use {@link ChatInstanceMessaging.restartConversation} instead.
3102
+ */
3103
+ restartConversation: () => Promise<void>;
3104
+ /**
3105
+ * Initiates a doAutoScroll on the currently visible chat panel.
3106
+ */
3107
+ doAutoScroll: () => void;
3108
+ /**
3109
+ * Either increases or decreases the internal counter that indicates whether the "assistant is loading" indicator is
3110
+ * shown. If the count is greater than zero, then the indicator is shown. Values of "increase" or "decrease" will
3111
+ * increase or decrease the value. Any other value will log an error.
3112
+ */
3113
+ updateIsMessageLoadingCounter: (direction: IncreaseOrDecrease) => void;
3114
+ /**
3115
+ * Either increases or decreases the internal counter that indicates whether the hydration fullscreen loading state is
3116
+ * shown. If the count is greater than zero, then the indicator is shown. Values of "increase" or "decrease" will
3117
+ * increase or decrease the value. Any other value will log an error.
3118
+ */
3119
+ updateIsChatLoadingCounter: (direction: IncreaseOrDecrease) => void;
3120
+ /**
3121
+ * The state of notifications in the chat.
3122
+ *
3123
+ * @experimental
3124
+ */
3125
+ notifications: ChatInstanceNotifications;
3126
+ /**
3127
+ * Actions that are related to a service desk integration.
3128
+ */
3129
+ serviceDesk: ChatInstanceServiceDeskActions;
3130
+ /**
3131
+ * Remove any record of the current session from the browser's SessionStorage.
3132
+ *
3133
+ * @param keepOpenState If we are destroying the session to restart the chat this can be used to preserve if the web
3134
+ * chat is open.
3135
+ */
3136
+ destroySession: (keepOpenState?: boolean) => Promise<void>;
3137
+ }
3138
+ /**
3139
+ * @category Instance
3140
+ */
3141
+ type IncreaseOrDecrease = "increase" | "decrease";
3142
+ /**
3143
+ * This interface represents the options for when a MessageRequest is sent to the server with the send method.
3144
+ *
3145
+ * @category Instance
3146
+ */
3147
+ interface SendOptions {
3148
+ /**
3149
+ * If you want to send a message to the API, but NOT have it show up in the UI, set this to true. The "pre:send"
3150
+ * and "send" events will still be fired but the message will not be added to the local message list displayed in
3151
+ * the UI. Note that the response message will still be added.
3152
+ */
3153
+ silent?: boolean;
3154
+ }
3155
+ /**
3156
+ * An object of elements we expose to developers to write to. Be sure to check the documentation of the React or
3157
+ * web component you are using for how to make use of this, as it differs based on implementation.
3158
+ *
3159
+ * @category Instance
3160
+ */
3161
+ type WriteableElements = Record<WriteableElementName, HTMLElement>;
3162
+ /**
3163
+ * @category Instance
3164
+ */
3165
+ declare enum WriteableElementName {
3166
+ /**
3167
+ * An element that appears in the AI theme only and is shown beneath the title and description in the AI tooltip
3168
+ * content.
3169
+ */
3170
+ AI_TOOLTIP_AFTER_DESCRIPTION_ELEMENT = "aiTooltipAfterDescriptionElement",
3171
+ /**
3172
+ * An element that appears in the main message body directly above the welcome node.
3173
+ */
3174
+ WELCOME_NODE_BEFORE_ELEMENT = "welcomeNodeBeforeElement",
3175
+ /**
3176
+ * An element that appears in the header on a new line. Only visible while talking to the assistant.
3177
+ */
3178
+ HEADER_BOTTOM_ELEMENT = "headerBottomElement",
3179
+ /**
3180
+ * An element that appears after the messages area and before the input area.
3181
+ */
3182
+ BEFORE_INPUT_ELEMENT = "beforeInputElement",
3183
+ /**
3184
+ * An element that appears above the input field on the home screen.
3185
+ */
3186
+ HOME_SCREEN_BEFORE_INPUT_ELEMENT = "homeScreenBeforeInputElement",
3187
+ /**
3188
+ * An element that appears on the home screen after the conversation starters.
3189
+ */
3190
+ HOME_SCREEN_AFTER_STARTERS_ELEMENT = "homeScreenAfterStartersElement",
3191
+ /**
3192
+ * An element that appears on the home screen above the welcome message and conversation starters.
3193
+ */
3194
+ HOME_SCREEN_HEADER_BOTTOM_ELEMENT = "homeScreenHeaderBottomElement",
3195
+ /**
3196
+ * An element to be housed in the custom panel.
3197
+ */
3198
+ CUSTOM_PANEL_ELEMENT = "customPanelElement"
3199
+ }
3200
+ /**
3201
+ * Add notification messages to the chat. This component has some a11y bugs before we can mark it complete.
3202
+ *
3203
+ * @category Instance
3204
+ *
3205
+ * @experimental
3206
+ */
3207
+ interface ChatInstanceNotifications {
3208
+ /**
3209
+ * Add a system level notification to the list of system notifications.
3210
+ */
3211
+ addNotification: (notification: NotificationMessage) => void;
3212
+ /**
3213
+ * Remove a system level notification from the list of system notifications.
3214
+ */
3215
+ removeNotifications: (groupID: string) => void;
3216
+ /**
3217
+ * Remove all system level notifications from the list of system notifications.
3218
+ */
3219
+ removeAllNotifications: () => void;
3220
+ }
3221
+ /**
3222
+ * @category Instance
3223
+ */
3224
+ type ChangeFunction = (text: string) => void;
3225
+ /**
3226
+ * Upload options. Currently only applies to conversations with a human agent.
3227
+ *
3228
+ * @category Instance
3229
+ */
3230
+ interface FileUploadCapabilities {
3231
+ /**
3232
+ * Indicates that file uploads may be performed by the user.
3233
+ */
3234
+ allowFileUploads: boolean;
3235
+ /**
3236
+ * If file uploads are allowed, this indicates if more than one file may be selected at a time. The default is false.
3237
+ */
3238
+ allowMultipleFileUploads: boolean;
3239
+ /**
3240
+ * If file uploads are allowed, this is the set a file types that are allowed. This is filled into the "accept"
3241
+ * field for the file input element.
3242
+ */
3243
+ allowedFileUploadTypes: string;
3244
+ }
3245
+ /**
3246
+ * Start or end conversations with human agent.
3247
+ *
3248
+ * @category Instance
3249
+ */
3250
+ interface ChatInstanceServiceDeskActions {
3251
+ /**
3252
+ * Ends the conversation with a human agent. This does not request confirmation from the user first. If the user
3253
+ * is not connected or connecting to a human agent, this function has no effect. You can determine if the user is
3254
+ * connected or connecting by calling {@link ChatInstance.getState}. Note that this function
3255
+ * returns a Promise that only resolves when the conversation has ended. This includes after the
3256
+ * {@link BusEventType.HUMAN_AGENT_PRE_END_CHAT} and {@link BusEventType.HUMAN_AGENT_END_CHAT} events have been fired and
3257
+ * resolved.
3258
+ */
3259
+ endConversation: () => Promise<void>;
3260
+ /**
3261
+ * Sets the suspended state for an agent conversation. A conversation can be suspended or un-suspended only if the
3262
+ * user is currently connecting or connected to an agent. If a conversation is suspended, then messages from the user
3263
+ * will no longer be routed to the service desk and incoming messages from the service desk will not be displayed. In
3264
+ * addition, the current connection status with an agent will not be shown.
3265
+ */
3266
+ updateIsSuspended: (isSuspended: boolean) => Promise<void>;
3267
+ }
3268
+
3269
+ /**
3270
+ * The types of corners the chat can have.
3271
+ *
3272
+ * @category Config
3273
+ */
3274
+ declare enum CornersType {
3275
+ /**
3276
+ * Makes the corners on the chat component rounded.
3277
+ */
3278
+ ROUND = "round",
3279
+ /**
3280
+ * Makes the corners on the chat component square.
3281
+ */
3282
+ SQUARE = "square"
3283
+ }
3284
+
3285
+ /**
3286
+ * A conversation starter button on the home screen. Currently, only label is provided by tooling.
3287
+ *
3288
+ * @category Config
3289
+ */
3290
+ interface HomeScreenStarterButton {
3291
+ /**
3292
+ * The display label of the button. This is also the value that is sent as the user's utterance to the assistant
3293
+ * when the button is clicked.
3294
+ */
3295
+ label: string;
3296
+ /**
3297
+ * Indicates if the button was previously clicked and should be displayed as selected.
3298
+ */
3299
+ isSelected?: boolean;
3300
+ }
3301
+ /**
3302
+ * Starter buttons that appear on home screen.
3303
+ *
3304
+ * @category Config
3305
+ */
3306
+ interface HomeScreenStarterButtons {
3307
+ isOn?: boolean;
3308
+ buttons?: HomeScreenStarterButton[];
3309
+ }
3310
+ /**
3311
+ * Configuration for the optional home screen that appears before the assistant chat window.
3312
+ *
3313
+ * @category Config
3314
+ */
3315
+ interface HomeScreenConfig {
3316
+ /**
3317
+ * If the home page is turned on via config or remote config.
3318
+ */
3319
+ isOn?: boolean;
3320
+ /**
3321
+ * The greeting to show to the user to prompt them to start a conversation.
3322
+ */
3323
+ greeting?: string;
3324
+ /**
3325
+ * Optional conversation starter utterances that are displayed as buttons.
3326
+ */
3327
+ starters?: HomeScreenStarterButtons;
3328
+ /**
3329
+ * Do not show the greeting or starters.
3330
+ */
3331
+ customContentOnly?: boolean;
3332
+ /**
3333
+ * Defaults to false. If enabled, a user can not navigate back to the home screen after they have sent a message to the
3334
+ * assistant. If false, the home screen is navigatable after an initial message is sent.
3335
+ */
3336
+ disableReturn?: boolean;
3337
+ }
3338
+ /**
3339
+ * Current state of home screen (currently, limited to if it is open or closed).
3340
+ *
3341
+ * @category Config
3342
+ */
3343
+ interface HomeScreenState {
3344
+ /**
3345
+ * Indicates if the home screen is currently open.
3346
+ */
3347
+ isHomeScreenOpen: boolean;
3348
+ /**
3349
+ * Indicates if the home screen should display a "return to assistant" button. This button is displayed when the user
3350
+ * has clicked the "back to home" button from the assistant.
3351
+ */
3352
+ showBackToAssistant: boolean;
3353
+ }
3354
+
3355
+ /**
3356
+ * Valid public CSS variables that can be controlled when white labeling is disabled.
3357
+ * These variables map to CSS custom properties used in styling the AI chat interface.
3358
+ *
3359
+ * Keys map to the underlying `--cds-aichat-…` custom properties.
3360
+ *
3361
+ * @category Config
3362
+ */
3363
+ declare enum LayoutCustomProperties {
3364
+ /** Minimum height of the chat container (float layout). */
3365
+ height = "height",
3366
+ /** Maximum height of the chat container (float layout). */
3367
+ max_height = "max-height",
3368
+ /** Width of the chat panel (float layout). */
3369
+ width = "width",
3370
+ /** z-index of the chat overlay or container (float layout). */
3371
+ z_index = "z-index"
3372
+ }
3373
+
3374
+ /**
3375
+ * Configuration for the launcher.
3376
+ *
3377
+ * @category Config
3378
+ */
3379
+ interface LauncherConfig {
3380
+ /**
3381
+ * If the launcher is visible. Defaults to true.
3382
+ */
3383
+ isOn?: boolean;
3384
+ /**
3385
+ * Properties specific to the mobile launcher.
3386
+ */
3387
+ mobile?: LauncherCallToActionConfig;
3388
+ /**
3389
+ * Properties specific to the desktop launcher.
3390
+ */
3391
+ desktop?: LauncherCallToActionConfig;
3392
+ }
3393
+ /**
3394
+ * @category Config
3395
+ */
3396
+ interface LauncherCallToActionConfig {
3397
+ /**
3398
+ * If the launcher will expand with a call to action.
3399
+ */
3400
+ isOn?: boolean;
3401
+ /**
3402
+ * The title that will be used by the expanded state of the launcher. If nothing is set in the config then a default
3403
+ * translated string will be used.
3404
+ */
3405
+ title?: string;
3406
+ /**
3407
+ * The amount of time to wait before extending the launcher. If nothing is set then the default time of
3408
+ * 15s will be used.
3409
+ */
3410
+ timeToExpand?: number;
3411
+ /**
3412
+ * An optional override of the icon shown on the launcher.
3413
+ */
3414
+ avatarUrlOverride?: string;
3415
+ }
3416
+
3417
+ /**
3418
+ * This file contains the definition for the public application configuration operations that are provided by the
3419
+ * host page.
3420
+ */
3421
+ /**
3422
+ * The raw strings used for {@link PublicConfig.strings}. Presented in ICU format.
3423
+ *
3424
+ * @category Config
3425
+ */
3426
+ declare const enLanguagePack: {
3427
+ ai_slug_label: string;
3428
+ ai_slug_title: string;
3429
+ ai_slug_description: string;
3430
+ components_overflow_ariaLabel: string;
3431
+ components_swiper_currentLabel: string;
3432
+ errors_communicating: string;
3433
+ errors_imageSource: string;
3434
+ errors_videoSource: string;
3435
+ errors_audioSource: string;
3436
+ errors_iframeSource: string;
3437
+ errors_singleMessage: string;
3438
+ errors_ariaMessageRetrying: string;
3439
+ errors_ariaMessageFailed: string;
3440
+ errors_noHumanAgentsAvailable: string;
3441
+ errors_noHumanAgentsJoined: string;
3442
+ errors_connectingToHumanAgent: string;
3443
+ errors_busy: string;
3444
+ errors_agentAppSessionExpired: string;
3445
+ errors_generalContent: string;
3446
+ errors_somethingWrong: string;
3447
+ input_ariaLabel: string;
3448
+ input_placeholder: string;
3449
+ input_buttonLabel: string;
3450
+ input_uploadButtonLabel: string;
3451
+ window_title: string;
3452
+ window_ariaChatRegion: string;
3453
+ window_ariaChatRegionNamespace: string;
3454
+ window_ariaWindowOpened: string;
3455
+ window_ariaWindowClosed: string;
3456
+ window_ariaWindowLoading: string;
3457
+ launcher_isOpen: string;
3458
+ launcher_isClosed: string;
3459
+ launcher_desktopGreeting: string;
3460
+ launcher_mobileGreeting: string;
3461
+ launcher_ariaIsExpanded: string;
3462
+ launcher_closeButton: string;
3463
+ messages_youSaid: string;
3464
+ messages_assistantSaid: string;
3465
+ messages_agentSaid: string;
3466
+ messages_searchResults: string;
3467
+ messages_searchResultsLink: string;
3468
+ messages_searchResultsOpenDocument: string;
3469
+ messages_searchResultsOpenDocumentWithLabel: string;
3470
+ messages_searchResultsExpand: string;
3471
+ messages_searchResultsCollapse: string;
3472
+ messages_assistantIsLoading: string;
3473
+ messages_agentIsTyping: string;
3474
+ messages_scrollHandle: string;
3475
+ messages_scrollHandleDetailed: string;
3476
+ messages_scrollHandleEnd: string;
3477
+ messages_scrollHandleEndDetailed: string;
3478
+ messages_scrollMoreButton: string;
3479
+ message_labelAssistant: string;
3480
+ message_labelYou: string;
3481
+ notifications_toastClose: string;
3482
+ buttons_restart: string;
3483
+ buttons_cancel: string;
3484
+ buttons_retry: string;
3485
+ options_select: string;
3486
+ options_ariaOptionsDisabled: string;
3487
+ header_previewLinkTitle: string;
3488
+ header_ariaAssistantAvatar: string;
3489
+ header_overflowMenu_options: string;
3490
+ homeScreen_returnToAssistant: string;
3491
+ homeScreen_returnToHome: string;
3492
+ homeScreen_overflowMenuHomeScreen: string;
3493
+ homeScreen_ariaQuickStartListButton: string;
3494
+ homeScreen_ariaQuickStartListOpened: string;
3495
+ homeScreen_ariaQuickStartListClosed: string;
3496
+ default_agent_availableMessage: string;
3497
+ default_agent_unavailableMessage: string;
3498
+ agent_reason_error: string;
3499
+ agent_sdMissingWarning: string;
3500
+ agent_noName: string;
3501
+ agent_chatTitle: string;
3502
+ agent_startChat: string;
3503
+ agent_connecting: string;
3504
+ agent_agentNoNameTitle: string;
3505
+ agent_agentJoinedName: string;
3506
+ agent_agentJoinedNoName: string;
3507
+ agent_youConnectedWarning: string;
3508
+ agent_connectingMinutes: string;
3509
+ agent_connectingQueue: string;
3510
+ agent_ariaHumanAgentAvatar: string;
3511
+ agent_ariaGenericAvatar: string;
3512
+ agent_ariaGenericAssistantAvatar: string;
3513
+ agent_youEndedChat: string;
3514
+ agent_conversationWasEnded: string;
3515
+ agent_disconnected: string;
3516
+ agent_reconnected: string;
3517
+ agent_agentLeftChat: string;
3518
+ agent_agentLeftChatNoName: string;
3519
+ agent_agentEndedChat: string;
3520
+ agent_agentEndedChatNoName: string;
3521
+ agent_transferring: string;
3522
+ agent_transferringNoName: string;
3523
+ agent_endChat: string;
3524
+ agent_confirmSuspendedEndChatTitle: string;
3525
+ agent_confirmSuspendedEndChatMessage: string;
3526
+ agent_confirmCancelRequestTitle: string;
3527
+ agent_confirmCancelRequestMessage: string;
3528
+ agent_confirmCancelRequestNo: string;
3529
+ agent_confirmCancelRequestYes: string;
3530
+ agent_confirmEndChat: string;
3531
+ agent_confirmEndChatNo: string;
3532
+ agent_confirmEndChatYes: string;
3533
+ agent_confirmEndSuspendedYes: string;
3534
+ agent_assistantReturned: string;
3535
+ agent_newMessage: string;
3536
+ agent_cardButtonChatRequested: string;
3537
+ agent_cardButtonConnected: string;
3538
+ agent_cardButtonChatEnded: string;
3539
+ agent_cardMessageChatEnded: string;
3540
+ agent_cardMessageConnected: string;
3541
+ agent_connectButtonCancel: string;
3542
+ agent_connectedButtonEndChat: string;
3543
+ agent_connectWaiting: string;
3544
+ agent_defaultMessageToHumanAgent: string;
3545
+ agent_inputPlaceholderConnecting: string;
3546
+ agent_inputPlaceholderReconnecting: string;
3547
+ agent_sharingStopSharingButton: string;
3548
+ agent_sharingRequestTitle: string;
3549
+ agent_sharingRequestMessage: string;
3550
+ agent_sharingAcceptButton: string;
3551
+ agent_sharingDeclineButton: string;
3552
+ agent_sharingRequested: string;
3553
+ agent_sharingAccepted: string;
3554
+ agent_sharingDeclined: string;
3555
+ agent_sharingCancelled: string;
3556
+ agent_sharingEnded: string;
3557
+ agent_suspendedWarning: string;
3558
+ icon_ariaUnreadMessages: string;
3559
+ showMore: string;
3560
+ showMoreResults: string;
3561
+ disclaimer_title: string;
3562
+ disclaimer_accept: string;
3563
+ general_ariaCloseInformationOverlay: string;
3564
+ general_ariaAnnounceOpenedInformationOverlay: string;
3565
+ general_ariaAnnounceClosedInformationOverlay: string;
3566
+ general_ariaAnnounceEscapeOverlay: string;
3567
+ general_returnToAssistant: string;
3568
+ conversationalSearch_streamingIncomplete: string;
3569
+ conversationalSearch_viewSourceDocument: string;
3570
+ conversationalSearch_citationsLabel: string;
3571
+ conversationalSearch_toggleCitations: string;
3572
+ conversationalSearch_responseStopped: string;
3573
+ launcher_chatNow: string;
3574
+ iframe_ariaSourceLoaded: string;
3575
+ iframe_ariaImageAltText: string;
3576
+ iframe_ariaClosePanel: string;
3577
+ iframe_ariaOpenedPanel: string;
3578
+ iframe_ariaClosedPanel: string;
3579
+ iframe_ariaClickPreviewCard: string;
3580
+ datePicker_chooseDate: string;
3581
+ datePicker_confirmDate: string;
3582
+ fileSharing_fileTooLarge: string;
3583
+ fileSharing_ariaAnnounceSuccess: string;
3584
+ fileSharing_fileIcon: string;
3585
+ fileSharing_removeButtonTitle: string;
3586
+ fileSharing_statusUploading: string;
3587
+ fileSharing_uploadFailed: string;
3588
+ fileSharing_agentMessageText: string;
3589
+ fileSharing_request: string;
3590
+ carousel_prevNavButton: string;
3591
+ carousel_nextNavButton: string;
3592
+ input_completionsTagApp: string;
3593
+ input_completionsTagAssistant: string;
3594
+ table_filterPlaceholder: string;
3595
+ table_previousPage: string;
3596
+ table_nextPage: string;
3597
+ table_itemsPerPage: string;
3598
+ table_paginationSupplementalText: string;
3599
+ table_paginationStatus: string;
3600
+ feedback_positiveLabel: string;
3601
+ feedback_negativeLabel: string;
3602
+ feedback_defaultTitle: string;
3603
+ feedback_defaultPrompt: string;
3604
+ feedback_defaultPlaceholder: string;
3605
+ feedback_submitLabel: string;
3606
+ feedback_cancelLabel: string;
3607
+ input_stopResponse: string;
3608
+ messages_responseStopped: string;
3609
+ chainOfThought_stepTitle: string;
3610
+ chainOfThought_inputLabel: string;
3611
+ chainOfThought_outputLabel: string;
3612
+ chainOfThought_toolLabel: string;
3613
+ chainOfThought_statusSucceededLabel: string;
3614
+ chainOfThought_statusFailedLabel: string;
3615
+ chainOfThought_statusProcessingLabel: string;
3616
+ chainOfThought_explainabilityLabel: string;
3617
+ };
3618
+ /**
3619
+ * A language pack represents the set of display strings for a particular language.
3620
+ * It defines all the text strings that can be customized for different languages.
3621
+ *
3622
+ * @category Config
3623
+ */
3624
+ type LanguagePack = typeof enLanguagePack;
3625
+ /**
3626
+ * Configuration interface for Carbon AI Chat.
3627
+ *
3628
+ * @category Config
3629
+ */
3630
+ interface PublicConfig {
3631
+ /**
3632
+ * This is a one-off listener for catastrophic errors. This is used instead of a normal event bus handler because this function can be
3633
+ * defined and called before the event bus has been created.
3634
+ */
3635
+ onError?: (data: OnErrorData) => void;
3636
+ /**
3637
+ * By default, the chat window will be rendered in a "closed" state.
3638
+ */
3639
+ openChatByDefault?: boolean;
3640
+ /**
3641
+ * Disclaimer screen configuration.
3642
+ *
3643
+ * If `disclaimerHTML` changes after the disclaimer has been accepted, we request a user to accept again.
3644
+ */
3645
+ disclaimer?: DisclaimerPublicConfig;
3646
+ /**
3647
+ * This value is only used when a custom element is being used to render the widget. By default, a number of
3648
+ * enhancements to the widget are activated on mobile devices which can interfere with a custom element. This
3649
+ * value can be used to disable those enhancements while using a custom element.
3650
+ */
3651
+ disableCustomElementMobileEnhancements?: boolean;
3652
+ /**
3653
+ * Add a bunch of noisy console.log messages!
3654
+ */
3655
+ debug?: boolean;
3656
+ /**
3657
+ * Which Carbon theme tokens to inject. If unset (falsy), the chat inherits tokens from the host page.
3658
+ * Set to a specific theme to force token injection.
3659
+ */
3660
+ injectCarbonTheme?: CarbonTheme;
3661
+ /**
3662
+ * Enables Carbon AI theme styling. Defaults to true.
3663
+ */
3664
+ aiEnabled?: boolean;
3665
+ /**
3666
+ * This is a factory for producing custom implementations of service desks. If this value is set, then this will
3667
+ * be used to create an instance of a {@link ServiceDesk} when the user attempts to connect to an agent.
3668
+ *
3669
+ * If it is changed in the middle of a conversation (you should obviously avoid this) the conversation with the
3670
+ * human agent will be restarted.
3671
+ */
3672
+ serviceDeskFactory?: (parameters: ServiceDeskFactoryParameters) => Promise<ServiceDesk>;
3673
+ /**
3674
+ * Any public config to apply to service desks.
3675
+ *
3676
+ * If it is changed in the middle of a conversation (you should obviously avoid this) the conversation with the
3677
+ * human agent will be restarted.
3678
+ */
3679
+ serviceDesk?: ServiceDeskPublicConfig;
3680
+ /**
3681
+ * If the Carbon AI Chat should grab focus if the chat is open on page load.
3682
+ */
3683
+ shouldTakeFocusIfOpensAutomatically?: boolean;
3684
+ /**
3685
+ * An optional namespace that can be added to the Carbon AI Chat that must be 30 characters or under. This value is
3686
+ * intended to enable multiple instances of the Carbon AI Chat to be used on the same page. The namespace for this web
3687
+ * chat. This value is used to generate a value to append to anything unique (id, session keys, etc) to allow
3688
+ * multiple Carbon AI Chats on the same page.
3689
+ *
3690
+ * Note: this value is used in the aria region label for the Carbon AI Chat. This means this value will be read out loud
3691
+ * by users using a screen reader.
3692
+ */
3693
+ namespace?: string;
3694
+ /**
3695
+ * Indicates if Carbon AI Chat should sanitize HTML from the assistant.
3696
+ */
3697
+ shouldSanitizeHTML?: boolean;
3698
+ /**
3699
+ * Extra config for controlling the behavior of the header.
3700
+ */
3701
+ header?: HeaderConfig;
3702
+ /**
3703
+ * The config object for changing Carbon AI Chat's layout.
3704
+ */
3705
+ layout?: LayoutConfig;
3706
+ /**
3707
+ * Config options for controlling messaging.
3708
+ */
3709
+ messaging?: PublicConfigMessaging;
3710
+ /**
3711
+ * Sets the chat into a read only mode for displaying old conversations.
3712
+ */
3713
+ isReadonly?: boolean;
3714
+ /**
3715
+ * Sets the name of the assistant. Defaults to "watsonx". Used in screen reader announcements and error messages.
3716
+ */
3717
+ assistantName?: string;
3718
+ /**
3719
+ * The locale to use for the widget. This controls the language pack and regional formatting.
3720
+ * Example values include: 'en', 'en-us', 'fr', 'es'.
3721
+ */
3722
+ locale?: string;
3723
+ /**
3724
+ * Configuration for the homescreen.
3725
+ *
3726
+ * If you change anything but `is_on` after the chat session has started, the chat will handle it gracefully.
3727
+ *
3728
+ * If you turn on the homescreen after the user has already started chatting, it will show up in the header as
3729
+ * an icon, but the user won't be forced to go back to the homescreen (unlike turning on the disclaimer mid-chat).
3730
+ */
3731
+ homescreen?: HomeScreenConfig;
3732
+ /**
3733
+ * Configuration for the launcher.
3734
+ */
3735
+ launcher?: LauncherConfig;
3736
+ /**
3737
+ * Configuration for the main input field on the chat.
3738
+ */
3739
+ input?: InputConfig;
3740
+ /**
3741
+ * Optional partial language pack overrides. Values merge with defaults.
3742
+ */
3743
+ strings?: DeepPartial<LanguagePack>;
3744
+ }
3745
+ /**
3746
+ * A single menu option.
3747
+ *
3748
+ * @category Config
3749
+ */
3750
+ interface CustomMenuOption {
3751
+ /**
3752
+ * The text to display for the menu option.
3753
+ */
3754
+ text: string;
3755
+ /**
3756
+ * The callback handler to call when the option is selected. Provide this of "url".
3757
+ */
3758
+ handler: () => void;
3759
+ }
3760
+ /**
3761
+ * @category Config
3762
+ */
3763
+ declare enum MinimizeButtonIconType {
3764
+ /**
3765
+ * This shows an "X" icon.
3766
+ */
3767
+ CLOSE = "close",
3768
+ /**
3769
+ * This shows a "-" icon.
3770
+ */
3771
+ MINIMIZE = "minimize",
3772
+ /**
3773
+ * This shows an icon that indicates that the Carbon AI Chat can be collapsed into a side panel.
3774
+ */
3775
+ SIDE_PANEL_LEFT = "side-panel-left",
3776
+ /**
3777
+ * This shows an icon that indicates that the Carbon AI Chat can be collapsed into a side panel.
3778
+ */
3779
+ SIDE_PANEL_RIGHT = "side-panel-right"
3780
+ }
3781
+ /**
3782
+ * Configuration for the input field in the main chat and homescreen.
3783
+ *
3784
+ * @category Config
3785
+ */
3786
+ interface InputConfig {
3787
+ /**
3788
+ * The maximum number of characters allowed in the input field. Defaults to 10000.
3789
+ */
3790
+ maxInputCharacters?: number;
3791
+ }
3792
+ /**
3793
+ * Configuration for the main header of the chat.
3794
+ *
3795
+ * @category Config
3796
+ */
3797
+ interface HeaderConfig {
3798
+ /**
3799
+ * Indicates the icon to use for the close button in the header.
3800
+ */
3801
+ minimizeButtonIconType?: MinimizeButtonIconType;
3802
+ /**
3803
+ * Hide the ability to minimize the Carbon AI Chat.
3804
+ */
3805
+ hideMinimizeButton?: boolean;
3806
+ /**
3807
+ * If true, shows the restart conversation button in the header of home screen and main chat.
3808
+ */
3809
+ showRestartButton?: boolean;
3810
+ /**
3811
+ * The chat header title.
3812
+ */
3813
+ title?: string;
3814
+ /**
3815
+ * The name displayed after the title.
3816
+ */
3817
+ name?: string;
3818
+ /**
3819
+ * All the currently configured custom menu options.
3820
+ */
3821
+ menuOptions?: CustomMenuOption[];
3822
+ /**
3823
+ * Controls whether to show the AI label/slug in the header. Defaults to true.
3824
+ *
3825
+ * There is currently no version of this that does not include the AI theme
3826
+ * blue gradients.
3827
+ */
3828
+ showAiLabel?: boolean;
3829
+ }
3830
+ /**
3831
+ * @category Config
3832
+ */
3833
+ interface LayoutConfig {
3834
+ /**
3835
+ * Indicates if the Carbon AI Chat widget should keep its border and box-shadow.
3836
+ */
3837
+ showFrame?: boolean;
3838
+ /**
3839
+ * Indicates if content inside the Carbon AI Chat widget should be constrained to a max-width.
3840
+ *
3841
+ * At larger widths the card, carousel, options and conversational search response types
3842
+ * have pending issues.
3843
+ */
3844
+ hasContentMaxWidth?: boolean;
3845
+ /**
3846
+ * This flag is used to disable Carbon AI Chat's rounded corners.
3847
+ */
3848
+ corners?: CornersType;
3849
+ /**
3850
+ * CSS variable overrides for the chat UI.
3851
+ *
3852
+ * Keys correspond to values from `LayoutCustomProperties` (e.g. `LayoutCustomProperties.height`),
3853
+ * which map to the underlying `--cds-aichat-…` custom properties.
3854
+ * Values are raw CSS values such as `"420px"`, `"9999"`, etc.
3855
+ *
3856
+ * Example:
3857
+ * { height: "560px", width: "420px" }
3858
+ */
3859
+ customProperties?: Partial<Record<LayoutCustomProperties, string>>;
3860
+ }
3861
+ /**
3862
+ * Config options for controlling messaging.
3863
+ *
3864
+ * @category Config
3865
+ */
3866
+ interface PublicConfigMessaging {
3867
+ /**
3868
+ * Indicates if Carbon AI Chat should make a request for the welcome message when a new conversation begins. If this is
3869
+ * true, then Carbon AI Chat will start with an empty conversation.
3870
+ *
3871
+ * **Manual session management required**: Changes to this property after conversation has started have no effect.
3872
+ * To apply new welcome behavior, call `instance.messaging.restartConversation()`.
3873
+ */
3874
+ skipWelcome?: boolean;
3875
+ /**
3876
+ * Changes the timeout used by the message service when making message calls. The timeout is in seconds. The
3877
+ * default is 150 seconds. After this time, an error will be shown in the client and an Abort signal will be sent
3878
+ * to customSendMessage. If set to 0, the chat will never timeout.
3879
+ */
3880
+ messageTimeoutSecs?: number;
3881
+ /**
3882
+ * Controls how long AI chat should wait before showing the loading indicator. If set to 0, the chat will never show
3883
+ * the loading indicator. This is tied to either {@link ChatInstanceMessaging.addMessage} or
3884
+ * {@link ChatInstanceMessaging.addMessageChunk} being called after this message was sent.
3885
+ *
3886
+ * If set to 0, the chat will never automatically show a loading indicator.
3887
+ */
3888
+ messageLoadingIndicatorTimeoutSecs?: number;
3889
+ /**
3890
+ * A callback for Carbon AI Chat to use to send messages to your assistant.
3891
+ *
3892
+ * Carbon AI Chat will queue up any additional user messages until the Promise from a previous call to customSendMessage
3893
+ * has resolved. If you do not make customSendMessage async, it will be up to you to manage what happens when a message is
3894
+ * sent when the previous is still processing. If the Promise rejects, an error indicator will be displayed next to the user's message.
3895
+ *
3896
+ * If the request takes longer than PublicConfigMessaging.messageTimeoutSecs than the AbortSignal will be sent.
3897
+ */
3898
+ customSendMessage?: (request: MessageRequest, requestOptions: CustomSendMessageOptions, instance: ChatInstance) => Promise<void> | void;
3899
+ /**
3900
+ * This is a callback function that is used by Carbon AI Chat to retrieve history data for populating the Carbon AI Chat. If
3901
+ * this function is defined, it will be used instead of any other mechanism for fetching history.
3902
+ *
3903
+ * If this function is mutated after it was initially called, the chat does not re-call it.
3904
+ */
3905
+ customLoadHistory?: (instance: ChatInstance) => Promise<HistoryItem[]>;
3906
+ }
3907
+ /**
3908
+ * @category Config
3909
+ */
3910
+ interface DisclaimerPublicConfig {
3911
+ /**
3912
+ * If the disclaimer is turned on.
3913
+ */
3914
+ isOn: boolean;
3915
+ /**
3916
+ * HTML content to show in disclaimer.
3917
+ */
3918
+ disclaimerHTML: string;
3919
+ }
3920
+ /**
3921
+ * A string identifying what Carbon Theme we should base UI variables off of.
3922
+ * Defaults to "inherit". If you are not hosting the chat on a website that is Carbon styles, you will want to choose
3923
+ * once of the non-inherited values to inject the correct CSS custom property values into the code. See
3924
+ * https://carbondesignsystem.com/guidelines/color/tokens.
3925
+ *
3926
+ * @category Config
3927
+ */
3928
+ declare enum CarbonTheme {
3929
+ /**
3930
+ * Injects Carbon white theme tokens.
3931
+ */
3932
+ WHITE = "white",
3933
+ /**
3934
+ * Injects Carbon Gray 10 theme tokens.
3935
+ */
3936
+ G10 = "g10",
3937
+ /**
3938
+ * Injects Carbon Gray 90 theme tokens.
3939
+ */
3940
+ G90 = "g90",
3941
+ /**
3942
+ * Injects Carbon Gray 100 theme tokens.
3943
+ */
3944
+ G100 = "g100"
3945
+ }
3946
+ /**
3947
+ * The different categories of errors that the system can record. These values are published for end user consumption.
3948
+ *
3949
+ * @category Config
3950
+ */
3951
+ declare enum OnErrorType {
3952
+ /**
3953
+ * Indicates an error sending a message to the assistant. This error is only generated after all retries have
3954
+ * failed and the system has given up.
3955
+ */
3956
+ MESSAGE_COMMUNICATION = "MESSAGE_COMMUNICATION",
3957
+ /**
3958
+ * This indicates an error in one of the components that occurs as part of rendering the UI.
3959
+ */
3960
+ RENDER = "RENDER",
3961
+ /**
3962
+ * This indicates a known error with the configuration for a service desk. Fired when a connect_to_agent
3963
+ * response type is received, but none is configured.
3964
+ */
3965
+ INTEGRATION_ERROR = "INTEGRATION_ERROR",
3966
+ /**
3967
+ * This indicates that some error occurred while trying to hydrate the chat. This will prevent the chat from
3968
+ * functioning.
3969
+ */
3970
+ HYDRATION = "HYDRATION"
3971
+ }
3972
+ /**
3973
+ * Fired when a serious error in the chat occurs.
3974
+ *
3975
+ * @category Config
3976
+ */
3977
+ interface OnErrorData {
3978
+ /**
3979
+ * The type of error that occurred.
3980
+ */
3981
+ errorType: OnErrorType;
3982
+ /**
3983
+ * A message associated with the error.
3984
+ */
3985
+ message: string;
3986
+ /**
3987
+ * An extra blob of data associated with the error. This may be a stack trace for thrown errors.
3988
+ */
3989
+ otherData?: unknown;
3990
+ /**
3991
+ * If the error is of the severity that requires a whole restart of Carbon AI Chat.
3992
+ */
3993
+ catastrophicErrorType?: boolean;
3994
+ }
3995
+
3996
+ /**
3997
+ * A TypeScript definition file for ObjectMap.
3998
+ */
3999
+ /**
4000
+ * This interface represents an object which behaves like a map. The object contains a set of properties representing
4001
+ * keys in the map and the values of those properties are all of the same type (TPropertyType). The type of the keys
4002
+ * defaults to any string but you can specify a type that is a string enum instead if you want a map that contains
4003
+ * only keys for a given enum (or other similar type).
4004
+ *
4005
+ * @category Utilities
4006
+ */
4007
+ type ObjectMap<TPropertyType, TKeyType extends string | number = string> = Partial<Record<TKeyType, TPropertyType>>;
4008
+
4009
+ /**
4010
+ * Items stored in sessionStorage.
4011
+ *
4012
+ * @category Instance
4013
+ */
4014
+ interface PersistedState {
4015
+ /**
4016
+ * Indicates if this state was loaded from browser session storage or if was created as part of a new session.
4017
+ */
4018
+ wasLoadedFromBrowser: boolean;
4019
+ /**
4020
+ * The version of the Carbon AI Chat that this data is persisted for. If there are any breaking changes to the
4021
+ * application state and a user reloads and gets a new version of the widget, bad things might happen so we'll
4022
+ * just invalidate the persisted storage if we ever attempt to load an old version on Carbon AI Chat startup.
4023
+ */
4024
+ version: string;
4025
+ /**
4026
+ * Indicates which of the Carbon AI Chat views are visible and which are hidden.
4027
+ */
4028
+ viewState: ViewState;
4029
+ /**
4030
+ * Indicates if we should show an unread indicator on the launcher. This is set by
4031
+ * {@link ChatInstance.updateAssistantUnreadIndicatorVisibility} and will display an empty circle on
4032
+ * the launcher. This setting is overridden if there are any unread human agent messages in which case a circle
4033
+ * with a number is displayed.
4034
+ */
4035
+ showUnreadIndicator: boolean;
4036
+ /**
4037
+ * Indicates if the mobile launcher should be in the extended state.
4038
+ */
4039
+ mobileLauncherIsExtended: boolean;
4040
+ /**
4041
+ * Determines if the mobile launcher already played the extended animation and was reduced.
4042
+ */
4043
+ mobileLauncherWasReduced: boolean;
4044
+ /**
4045
+ * Determines if the mobile launcher previously played the bounce animation and should no longer be able to.
4046
+ */
4047
+ mobileLauncherDisableBounce: boolean;
4048
+ /**
4049
+ * Indicates the desktop launcher is in its expanded state.
4050
+ */
4051
+ desktopLauncherIsExpanded: boolean;
4052
+ /**
4053
+ * Indicates the desktop launcher has been minimized.
4054
+ */
4055
+ desktopLauncherWasMinimized: boolean;
4056
+ /**
4057
+ * The bounce turn the user is currently on in the sequence of bounces so that user doesn't start over in the
4058
+ * sequence. A turn is a full set of animations that are displayed when a bounce occurs and each turn of a bounce is
4059
+ * when a different bounce occurs at a different point in time. This is used for both the desktop and mobile launcher.
4060
+ */
4061
+ bounceTurn: number;
4062
+ /**
4063
+ * If the user has received a message beyond the welcome node. We use this to mark if the chat has been interacted
4064
+ * with. This flag is duplicated so the information is available before hydration and before the user is known.
4065
+ * Note that this property reflects only the last user and should only be used when an approximate value is
4066
+ * acceptable.
4067
+ */
4068
+ hasSentNonWelcomeMessage: boolean;
4069
+ /**
4070
+ * Map of if a disclaimer has been accepted on a given window.hostname value, keyed by hostname via
4071
+ * {@link ObjectMap}.
4072
+ */
4073
+ disclaimersAccepted: ObjectMap<boolean>;
4074
+ /**
4075
+ * State of home screen.
4076
+ */
4077
+ homeScreenState: HomeScreenState;
4078
+ /**
4079
+ * The persisted subset of the human agent state.
4080
+ */
4081
+ humanAgentState: PersistedHumanAgentState;
4082
+ }
4083
+
4084
+ /**
4085
+ * @category Config
4086
+ */
4087
+ interface ChatHeaderConfig {
4088
+ /**
4089
+ * The chat header title.
4090
+ */
4091
+ title?: string;
4092
+ /**
4093
+ * The name displayed after the title.
4094
+ */
4095
+ name?: string;
4096
+ }
4097
+
4098
+ /**
4099
+ * This component is mostly a pass-through. Its takes any properties passed into the ChatContainer
4100
+ * custom element and then renders the React Carbon AI Chat application while passing in properties.
4101
+ */
4102
+
4103
+ declare class ChatContainerInternal extends LitElement {
4104
+ /**
4105
+ * The config to use to load Carbon AI Chat. Note that the "onLoad" property is overridden by this component. If you
4106
+ * need to perform any actions after Carbon AI Chat been loaded, use the "onBeforeRender" or "onAfterRender" props.
4107
+ */
4108
+ config: PublicConfig;
4109
+ /** Optional partial language pack overrides */
4110
+ strings?: DeepPartial<LanguagePack>;
4111
+ /** A factory for the {@link ServiceDesk} integration. */
4112
+ serviceDeskFactory?: (parameters: ServiceDeskFactoryParameters) => Promise<ServiceDesk>;
4113
+ /** Public configuration for the service desk integration. */
4114
+ serviceDesk?: ServiceDeskPublicConfig;
4115
+ /**
4116
+ * The optional HTML element to mount the chat to.
4117
+ */
4118
+ element?: HTMLElement;
4119
+ /**
4120
+ * This function is called before the render function of Carbon AI Chat is called. This function can return a Promise
4121
+ * which will cause Carbon AI Chat to wait for it before rendering.
4122
+ */
4123
+ onBeforeRender: (instance: ChatInstance) => Promise<void> | void;
4124
+ /**
4125
+ * This function is called after the render function of Carbon AI Chat is called. This function can return a Promise
4126
+ * which will cause Carbon AI Chat to wait for it before rendering.
4127
+ */
4128
+ onAfterRender: (instance: ChatInstance) => Promise<void> | void;
4129
+ firstUpdated(): void;
4130
+ updated(changedProperties: PropertyValues): void;
4131
+ /**
4132
+ * Track if a previous React 18+ root was already created so we don't create a memory leak on re-renders.
4133
+ */
4134
+ root: Root;
4135
+ /**
4136
+ * Cache the container we hand to React so we can reuse it between renders.
4137
+ */
4138
+ reactContainer?: HTMLDivElement;
4139
+ renderReactApp(): Promise<void>;
4140
+ private ensureReactRoot;
4141
+ disconnectedCallback(): void;
4142
+ }
4143
+ declare global {
4144
+ interface HTMLElementTagNameMap {
4145
+ "cds-aichat-internal": ChatContainerInternal;
4146
+ }
4147
+ }
4148
+
4149
+ /**
4150
+ * The cds-aichat-container managing creating slotted elements for user_defined responses and writable elements.
4151
+ * It then passes that slotted content into cds-aichat-internal. That component will boot up the full chat application
4152
+ * and pass the slotted elements into their slots.
4153
+ */
4154
+ declare class ChatContainer extends LitElement {
4155
+ config?: PublicConfig;
4156
+ onError?: (data: OnErrorData) => void;
4157
+ openChatByDefault?: boolean;
4158
+ disclaimer?: DisclaimerPublicConfig;
4159
+ disableCustomElementMobileEnhancements?: boolean;
4160
+ debug?: boolean;
4161
+ exposeServiceManagerForTesting?: boolean;
4162
+ injectCarbonTheme?: CarbonTheme;
4163
+ aiEnabled?: boolean;
4164
+ aiDisabled?: boolean;
4165
+ shouldTakeFocusIfOpensAutomatically?: boolean;
4166
+ namespace?: string;
4167
+ private enableFocusTrap?;
4168
+ shouldSanitizeHTML?: boolean;
4169
+ header?: HeaderConfig;
4170
+ input?: InputConfig;
4171
+ layout?: LayoutConfig;
4172
+ messaging?: PublicConfigMessaging;
4173
+ isReadonly?: boolean;
4174
+ assistantName?: string;
4175
+ locale?: string;
4176
+ homescreen?: HomeScreenConfig;
4177
+ launcher?: LauncherConfig;
4178
+ /** Optional partial language pack overrides */
4179
+ strings?: DeepPartial<LanguagePack>;
4180
+ /**
4181
+ * A factory to create a {@link ServiceDesk} integration instance.
4182
+ */
4183
+ serviceDeskFactory?: (parameters: ServiceDeskFactoryParameters) => Promise<ServiceDesk>;
4184
+ /**
4185
+ * Public configuration for the service desk integration.
4186
+ */
4187
+ serviceDesk?: ServiceDeskPublicConfig;
4188
+ /**
4189
+ * This function is called before the render function of Carbon AI Chat is called. This function can return a Promise
4190
+ * which will cause Carbon AI Chat to wait for it before rendering.
4191
+ */
4192
+ onBeforeRender: (instance: ChatInstance) => Promise<void> | void;
4193
+ /**
4194
+ * This function is called after the render function of Carbon AI Chat is called.
4195
+ */
4196
+ onAfterRender: (instance: ChatInstance) => Promise<void> | void;
4197
+ /**
4198
+ * The existing array of slot names for all user_defined components.
4199
+ */
4200
+ _userDefinedSlotNames: string[];
4201
+ /**
4202
+ * The existing array of slot names for all writeable elements.
4203
+ */
4204
+ _writeableElementSlots: string[];
4205
+ /**
4206
+ * The chat instance.
4207
+ */
4208
+ _instance: ChatInstance;
4209
+ /**
4210
+ * Adds the slot attribute to the element for the user_defined response type and then injects it into the component by
4211
+ * updating this._userDefinedSlotNames;
4212
+ */
4213
+ userDefinedHandler: (event: BusEventUserDefinedResponse | BusEventChunkUserDefinedResponse) => void;
4214
+ private get resolvedConfig();
4215
+ onBeforeRenderOverride: (instance: ChatInstance) => Promise<void>;
4216
+ addWriteableElementSlots(): void;
4217
+ /**
4218
+ * Renders the template while passing in class functionality
4219
+ */
4220
+ render(): lit_html.TemplateResult<1>;
4221
+ }
4222
+ declare global {
4223
+ interface HTMLElementTagNameMap {
4224
+ "cds-aichat-container": ChatContainer;
4225
+ }
4226
+ }
4227
+ /**
4228
+ * Attributes interface for the cds-aichat-container web component.
4229
+ * This interface extends {@link PublicConfig} with additional component-specific props,
4230
+ * flattening all config properties as top-level properties for better TypeScript IntelliSense.
4231
+ *
4232
+ * @category Web component
4233
+ */
4234
+ interface CdsAiChatContainerAttributes extends PublicConfig {
4235
+ /**
4236
+ * This function is called before the render function of Carbon AI Chat is called. This function can return a Promise
4237
+ * which will cause Carbon AI Chat to wait for it before rendering.
4238
+ */
4239
+ onBeforeRender?: (instance: ChatInstance) => Promise<void> | void;
4240
+ /**
4241
+ * This function is called after the render function of Carbon AI Chat is called.
4242
+ */
4243
+ onAfterRender?: (instance: ChatInstance) => Promise<void> | void;
4244
+ }
4245
+
4246
+ /**
4247
+ * Attributes interface for the cds-aichat-custom-element web component.
4248
+ * This interface extends {@link CdsAiChatContainerAttributes} and {@link PublicConfig} with additional component-specific props,
4249
+ * flattening all config properties as top-level properties for better TypeScript IntelliSense.
4250
+ *
4251
+ * @category Web component
4252
+ */
4253
+ interface CdsAiChatCustomElementAttributes extends PublicConfig {
4254
+ /**
4255
+ * This function is called before the render function of Carbon AI Chat is called. This function can return a Promise
4256
+ * which will cause Carbon AI Chat to wait for it before rendering.
4257
+ */
4258
+ onBeforeRender?: (instance: ChatInstance) => Promise<void> | void;
4259
+ /**
4260
+ * This function is called after the render function of Carbon AI Chat is called.
4261
+ */
4262
+ onAfterRender?: (instance: ChatInstance) => Promise<void> | void;
4263
+ /**
4264
+ * An optional listener for "view:change" events. Such a listener is required when using a custom element in order
4265
+ * to control the visibility of the Carbon AI Chat main window. If no callback is provided here, a default one will be
4266
+ * used that injects styling into the app that will show and hide the Carbon AI Chat main window and also change the
4267
+ * size of the custom element so it doesn't take up space when the main window is closed.
4268
+ *
4269
+ * You can provide a different callback here if you want custom behavior such as an animation when the main window
4270
+ * is opened or closed.
4271
+ *
4272
+ * Note that this function can only be provided before Carbon AI Chat is loaded. After Carbon AI Chat is loaded, the event
4273
+ * handler will not be updated.
4274
+ */
4275
+ onViewChange?: (event: BusEventViewChange, instance: ChatInstance) => void;
4276
+ }
4277
+
4278
+ /**
4279
+ * The user_defined message object passed into the renderUserDefinedResponse property on the main chat components.
4280
+ *
4281
+ * @category React
4282
+ */
4283
+ interface RenderUserDefinedState {
4284
+ /**
4285
+ * The entire message object received when the entire message (not just the individual messageItem) has finished processing.
4286
+ */
4287
+ fullMessage?: Message;
4288
+ /**
4289
+ * The messageItem after all partial chunks are received. This will first be set to the value of the `complete_item`
4290
+ * chunk.
4291
+ * Once the fullMessage is resolved, this value will update to the value of the item in the fullMessage, which will
4292
+ * be the same value unless you have done any post-processing mutations.
4293
+ */
4294
+ messageItem?: GenericItem;
4295
+ /**
4296
+ * An array of each user defined item partial chunk. Each chunk contains the new chunk information, they are not
4297
+ * concatenated for you. When messageItem has been set an no more chunks are expected, this property is removed
4298
+ * to avoid memory leaks.
4299
+ */
4300
+ partialItems?: DeepPartial<GenericItem>[];
4301
+ }
4302
+ /**
4303
+ * The type of the render function that is used to render user defined responses. This function should return a
4304
+ * component that renders the display for the message contained in the given event.
4305
+ *
4306
+ * @param state The BusEventUserDefinedResponse that was originally fired by Carbon AI Chat when the user defined response
4307
+ * was first fired.
4308
+ * @param instance The current instance of the Carbon AI Chat.
4309
+ *
4310
+ * @category React
4311
+ */
4312
+ type RenderUserDefinedResponse = (state: RenderUserDefinedState, instance: ChatInstance) => ReactNode;
4313
+ /**
4314
+ * A map of writeable element keys to a ReactNode to render to them.
4315
+ *
4316
+ * @category React
4317
+ */
4318
+ type RenderWriteableElementResponse = {
4319
+ [K in keyof WriteableElements]?: ReactNode;
4320
+ };
4321
+ /**
4322
+ * Properties for the ChatContainer React component. This interface extends
4323
+ * {@link PublicConfig} with additional component-specific props, flattening all
4324
+ * config properties as top-level props for better TypeScript IntelliSense.
4325
+ *
4326
+ * @category React
4327
+ */
4328
+ interface ChatContainerProps extends PublicConfig {
4329
+ /**
4330
+ * This function is called before the render function of Carbon AI Chat is called. This function can return a Promise
4331
+ * which will cause Carbon AI Chat to wait for it before rendering.
4332
+ */
4333
+ onBeforeRender?: (instance: ChatInstance) => Promise<void> | void;
4334
+ /**
4335
+ * This function is called after the render function of Carbon AI Chat is called. This function can return a Promise
4336
+ * which will cause Carbon AI Chat to wait for it before rendering.
4337
+ */
4338
+ onAfterRender?: (instance: ChatInstance) => Promise<void> | void;
4339
+ /**
4340
+ * This is the function that this component will call when a user defined response should be rendered.
4341
+ */
4342
+ renderUserDefinedResponse?: RenderUserDefinedResponse;
4343
+ /**
4344
+ * This is the render function this component will call when it needs to render a writeable element.
4345
+ */
4346
+ renderWriteableElements?: RenderWriteableElementResponse;
4347
+ }
4348
+
4349
+ /**
4350
+ * An enum of all of our data-testid we use. For some elements (like INPUT) they can appear in multiple "panels"
4351
+ * (e.g. on the home screen and in the main chat window). There are provided testids for "panels" as well so you
4352
+ * can first select a panel and then select the correct child.
4353
+ *
4354
+ * @category Testing
4355
+ *
4356
+ * @experimental
4357
+ */
4358
+ declare enum PageObjectId {
4359
+ /**
4360
+ * Minimize chat button in header.
4361
+ */
4362
+ CLOSE_CHAT = "close_chat",
4363
+ /**
4364
+ * The launcher button to open the chat. This id is maintained across desktop and mobile launchers.
4365
+ */
4366
+ LAUNCHER = "launcher_open_chat",
4367
+ /**
4368
+ * Input field.
4369
+ */
4370
+ INPUT = "input_field",
4371
+ /**
4372
+ * Input send button.
4373
+ */
4374
+ INPUT_SEND = "input_send",
4375
+ /**
4376
+ * The chat header title element.
4377
+ */
4378
+ HEADER_TITLE = "header_title",
4379
+ /**
4380
+ * The chat header name element.
4381
+ */
4382
+ HEADER_NAME = "header_name",
4383
+ /**
4384
+ * The main chat panel.
4385
+ */
4386
+ MAIN_PANEL = "main_panel",
4387
+ /**
4388
+ * Disclaimer panel.
4389
+ */
4390
+ DISCLAIMER_PANEL = "disclaimer_panel",
4391
+ /**
4392
+ * Disclaimer accept button.
4393
+ */
4394
+ DISCLAIMER_ACCEPT_BUTTON = "disclaimer_accept_button",
4395
+ /**
4396
+ * Homescreen Panel.
4397
+ */
4398
+ HOME_SCREEN_PANEL = "home_screen_panel",
4399
+ /**
4400
+ * Hydration/loading state panel.
4401
+ */
4402
+ HYDRATING_PANEL = "hydrating_panel",
4403
+ /**
4404
+ * Catastrophic error panel.
4405
+ */
4406
+ CATASTROPHIC_PANEL = "catastrophic_panel",
4407
+ /**
4408
+ * Iframe panel.
4409
+ */
4410
+ IFRAME_PANEL = "iframe_panel",
4411
+ /**
4412
+ * Conversational search panel.
4413
+ */
4414
+ CONVERSATIONAL_SEARCH_CITATION_PANEL = "conversational_search_citation_panel",
4415
+ /**
4416
+ * Custom panel.
4417
+ */
4418
+ CUSTOM_PANEL = "custom_panel",
4419
+ /**
4420
+ * A panel that opens from a button response.
4421
+ */
4422
+ BUTTON_RESPONSE_PANEL = "button_response_panel"
4423
+ }
4424
+ /**
4425
+ * Ids used for data-testid.
4426
+ *
4427
+ * @category Testing
4428
+ *
4429
+ * @experimental
4430
+ */
4431
+ type TestId = PageObjectId;
4432
+
4433
+ export { LayoutCustomProperties as L, WriteableElementName as W, BusEventType as _, FeedbackInteractionType as a1, MessageSendSource as a2, ViewChangeReason as a3, CancellationReason as a8, ScreenShareState as aA, ButtonItemKind as aR, ButtonItemType as aS, CarbonTheme as ab, enLanguagePack as ae, MinimizeButtonIconType as aj, OnErrorType as al, HumanAgentsOnlineStatus as at, ErrorType as ax, FileStatusValue as ay, ViewType as b, IFrameItemDisplayOption as b8, ChainOfThoughtStepStatus as bA, UserType as bI, MessageErrorState as bK, PageObjectId as bS, MessageInputType as bf, MessageResponseTypes as bk, OptionItemPreference as bm, WidthOptions as bu, HumanAgentMessageType as by, CornersType as n };
4434
+ export type { BusEventUserDefinedResponse as $, BusEventCustomPanelClose as A, BusEventViewChange as B, ChatContainerProps as C, BusEventCustomPanelOpen as D, EventBusHandler as E, FileUploadCapabilities as F, BusEventCustomPanelPreClose as G, BusEventCustomPanelPreOpen as H, IncreaseOrDecrease as I, BusEventFeedback as J, BusEventHistoryBegin as K, BusEventHistoryEnd as M, NotificationMessage as N, BusEventMessageItemCustom as O, PersistedState as P, BusEventPreReceive as Q, BusEventPreReset as R, SendOptions as S, TypeAndHandler as T, BusEventPreSend as U, ViewState as V, BusEventReceive as X, BusEventReset as Y, BusEventSend as Z, ChatInstance as a, DateItem as a$, BusEventViewPreChange as a0, HomeScreenConfig as a4, HomeScreenStarterButton as a5, HomeScreenStarterButtons as a6, HomeScreenState as a7, ChatInstanceMessaging as a9, ServiceDesk as aB, ServiceDeskCallback as aC, ServiceDeskCapabilities as aD, ServiceDeskErrorInfo as aE, ServiceDeskFactoryParameters as aF, ServiceDeskPublicConfig as aG, StartChatOptions as aH, UserMessageErrorInfo as aI, BaseGenericItem as aJ, MessageResponseOptions as aK, MessageResponseHistory as aL, MessageRequestHistory as aM, ResponseUserProfile as aN, AudioItem as aO, BaseMessageInput as aP, ButtonItem as aQ, CardItem as aT, CarouselItem as aU, Chunk as aV, CompleteItemChunk as aW, ConnectToHumanAgentItem as aX, ConnectToHumanAgentItemTransferInfo as aY, ConversationalSearchItem as aZ, ConversationalSearchItemCitation as a_, CustomSendMessageOptions as aa, CustomMenuOption as ac, DisclaimerPublicConfig as ad, HeaderConfig as af, InputConfig as ag, LanguagePack as ah, LayoutConfig as ai, OnErrorData as ak, PublicConfig as am, PublicConfigMessaging as an, PersistedHumanAgentState as ao, DeepPartial as ap, ObjectMap as aq, AdditionalDataToAgent as ar, AgentAvailability as as, ConnectingErrorInfo as au, DisconnectedErrorInfo as av, EndChatInfo as aw, FileUpload as az, EventInput as b0, EventInputData as b1, FinalResponseChunk as b2, GenericItem as b3, GenericItemMessageFeedbackCategories as b4, GridItem as b5, HorizontalCellAlignment as b6, IFrameItem as b7, ImageItem as b9, GenericItemMessageFeedbackOptions as bB, GenericItemMessageOptions as bC, Message as bD, PartialOrCompleteItemChunk as bE, PartialResponse as bF, MessageHistoryFeedback as bG, SearchResult as bH, HistoryItem as bJ, LauncherCallToActionConfig as bL, LauncherConfig as bM, CdsAiChatContainerAttributes as bN, CdsAiChatCustomElementAttributes as bO, RenderUserDefinedResponse as bP, RenderUserDefinedState as bQ, RenderWriteableElementResponse as bR, TestId as bT, InlineErrorItem as ba, ItemStreamingMetadata as bb, MediaItem as bc, MediaItemDimensions as bd, MessageInput as be, MessageItemPanelInfo as bg, MessageOutput as bh, MessageRequest as bi, MessageResponse as bj, OptionItem as bl, PartialItemChunk as bn, PauseItem as bo, StreamChunk as bp, TextItem as bq, UserDefinedItem as br, VerticalCellAlignment as bs, VideoItem as bt, WithBodyAndFooter as bv, WithWidthOptions as bw, SingleOption as bx, ChainOfThoughtStep as bz, ChatHeaderConfig as c, CustomPanelConfigOptions as d, CustomPanelInstance as e, CustomPanels as f, ChangeFunction as g, ChatInstanceNotifications as h, ChatInstanceServiceDeskActions as i, EventHandlers as j, PublicChatHumanAgentState as k, PublicChatState as l, WriteableElements as m, BusEvent as o, BusEventHumanAgentAreAnyAgentsOnline as p, BusEventHumanAgentEndChat as q, BusEventHumanAgentPreEndChat as r, BusEventHumanAgentPreReceive as s, BusEventHumanAgentPreSend as t, BusEventHumanAgentPreStartChat as u, BusEventHumanAgentReceive as v, BusEventHumanAgentSend as w, BusEventChatReady as x, BusEventChunkUserDefinedResponse as y, BusEventClosePanelButtonClicked as z };