@telia-ace/widget-conversation 1.0.21 → 1.0.24

package/README.md

@@ -58,32 +58,34 @@ const agent = conversation.createAgent({
 
 ## Writing to the conversation
 
+***`print()` accepts an array, which is considered best practice when writing to the conversation. The previous way of posting an object will still currently be supported, but is considered to be deprecated.**
+
 ### Posting, updating and removing content
 
-When managing content in the conversation you'll first need to create an `Agent`-object and then use its `print()` function. There are serveral types of entries in order to accommedate different types of content.
+When managing content in the conversation you'll first need to create an `Agent`-object and then use its `print()` function. There are serveral types of entries in order to accommodate different types of content.
 
-The `print(content: object)` function let's you return a `ConversationEntry` message that can be used to update and/or remove the content from the conversation.
+The `print(items: ConversationMessageItem[])` function let's you return a `ConversationEntry` message that can be used to update and/or remove the content from the conversation.
 
 ##### Example of simple text message
 
 ```ts
 // print user message
-conversation.user.print('Lorem ipsum');
+conversation.user.print([['text', 'Lorem ipsum']]);
 
 // print agent message
 const agent = conversation.createAgent();
-agent.print('Lorem ipsum');
+agent.print([['text', 'Lorem ipsum']]);
 ```
 
 ##### Example of updating or removing content
 
 ```ts
 const agent = conversation.createAgent();
-const entry = agent.print('Hello world!');
+const entry = agent.print([['text', 'Hello world!']]);
 
-entry.update({
+entry.update([
     // ...
-});
+]);
 
 entry.remove();
 ```
@@ -92,24 +94,55 @@ entry.remove();
 
 You can post an entry into the conversation with actions. You can specify a title, body and available actions. This is only supported for the `Agent` and will be displayed as a system message.
 
-| Name      | Type     | Description                                                   |
-| --------- | -------- | ------------------------------------------------------------- |
-| `title`   | `string` | Title for the entry.                                          |
-| `body`    | `string` | Body content for the entry. Supports HTML.                    |
-| `actions` | `object` | Key-value-pairs representing available actions for the entry. |
+This can be either in the form of a "ButtonList" or an "LinkList" as demostrated below.
+
+| Name      | Type     | Description                                  |
+| --------- | -------- | -------------------------------------------- |
+| `header`  | `string` | Header for the entry.                        |
+| `actions` | `array`  | Array of of available actions for the entry. |
 
 ##### Example of a list of actions
 
 ```ts
-agent.print({
-    title: 'Download invoices',
-    body: 'Click an invoice below to download a copy.',
-    actions: {
-        invoice_190201: 'Invoice 190201',
-        invoice_190301: 'Invoice 190301',
-        invoice_190401: 'Invoice 190401',
-    },
-});
+// example of button list
+agent.print([
+    [
+        'button-list',
+        {
+            header: 'Download invoices',
+            actions: [
+                {
+                    actionKey: 'invoice_190201',
+                    label: 'Invoice 190201',
+                },
+                {
+                    actionKey: 'invoice_190301',
+                    label: 'Invoice 190301',
+                },
+            ],
+        },
+    ],
+]);
+
+// here we use a link list instead, but with the same actions
+agent.print([
+    [
+        'link-list',
+        {
+            header: 'Download invoices',
+            actions: [
+                {
+                    actionKey: 'invoice_190201',
+                    label: 'Invoice 190201',
+                },
+                {
+                    actionKey: 'invoice_190301',
+                    label: 'Invoice 190301',
+                },
+            ],
+        },
+    ],
+]);
 ```
 
 ### Entry with a form
@@ -152,6 +185,56 @@ agent.print({
 });
 ```
 
+### Entry with a video call
+
+Use the `video-request` item type to create an entry representing an incoming video call. This entry can also have a form attached, which uses the `FormBuilder`-method and is handled by the `conversation.form` event. It is only supported for an `Agent` and will be displayed as a system message.
+
+| Name           | Type     | Description                                     |
+| -------------- | -------- | ----------------------------------------------- |
+| `header`       | `string` | Header for the entry.                           |
+| `acceptLabel`  | `string` | Label to be shown for the "accept call button"  |
+| `declineLabel` | `string` | Label to be shown for the "decline call button" |
+
+##### Example of an entry for an incoming video call
+
+```ts
+agent.print([
+    [
+        'video-request',
+        {
+            header: 'Video call',
+            accept: 'Accept',
+            decline: 'Decline',
+        },
+    ],
+]);
+```
+
+When the user presses one of these buttons to accept or decline the call, an action will be dispatched with actionKey `accept-video-call` or `decline-video-call`, depending on which button was clicked.
+
+Listening to these actions can be done as following:
+
+```ts
+component.actions.watch('conversation.action', (input, next) => {
+    if (input.actionKey === 'accept-video-call') {
+        // this will render an overlay over the widget,
+        // and prepare the widget for displaying the actual call
+        component.actions.dispatch('show-overlay', {});
+    } else if (input.actionKey === 'decline-video-call') {
+        // ...
+    }
+    return next(input);
+});
+```
+
+Use an overlay over the conversation to render your video call. The `show-overlay`-action, as described above, accomplishes this. After the overlay is rendered and ready it will dispatch another event: `overlay-mounted`. Use the HTML element this generates to render your video call.
+
+```ts
+component.actions.watch('overlay-mounted', (overlayElem, next) => {
+    // the overlayElem here may be used to render the ongoing call
+});
+```
+
 ### The loading and typing indicators
 
 When you need to fetch data from external resource you should use the `loading()` function on the `ConversationProvider` to inform the user that something is about to happen. Even in cases when the response is available immediately it gives a better user experience to present a loading indicator for a short while.
@@ -181,7 +264,7 @@ System message in the conversation are sent by using the `print` method on the `
 #### Example
 
 ```ts
-conversation.print('Hello world!');
+conversation.print([['text', 'Hello world!']]);
 ```
 
 ## Reading from the conversation

package/dist/components/conversation/ui/loader.d.ts

@@ -4,5 +4,5 @@ declare type Props = {
     className?: string;
     agentData?: ConversationMessageSender;
 };
-declare const ConversationLoader: React.FC<Props>;
+declare const ConversationLoader: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLDivElement>>;
 export default ConversationLoader;