Version: 8.3

Show chat history on any Freedom UI page

Level: advanced

note

This functionality is available for the Contact Center app in Creatio 8.3.3 and later.

Users might need to view the messages of a chat outside the Agent Inbox panel, for example, on the chat page or on the page of a related record. Since version 8.3.3, you can add the Conversation component to any Freedom UI page to show the messages of a chat. The component shows the messages that are stored in a view model attribute. The component is not available in the Freedom UI Designer element library. Add it in the source code of the Freedom UI page. Load the messages to the attribute using the crt.LoadConversationRequest base request or your own request handler. Learn more: Omnichannel inbox component.

1. Add the Conversation component to a page

Open the app in the Application Designer.
Open the page that should contain the component.
Click → Source code to open the source code of the Freedom UI page.

Set up the attributes of the component.

Go to the viewModelConfigDiff schema section.

Add the attribute that stores the messages and the ConversationEvent attribute.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "path": ["attributes"],
        "values": {
            /* Attribute that stores the messages. Creatio loads the
            messages only if the page declares this attribute. The
            value of the attribute does not matter: an empty value,
            null, or an empty array does not prevent loading. Set the
            initial value to an empty array. In the "replace" mode,
            Creatio overwrites the value of the attribute. In the
            "append" mode, Creatio adds the messages of the previous
            chat before the current value. */
            "UsrChatMessages": {
                "value": []
            },
            /* Queue of events for the component. Use exactly this
            name. Creatio writes events to the attribute with this
            name when it loads the messages. */
            "ConversationEvent": {
                "value": []
            }
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Add the component.

Go to the viewConfigDiff schema section.

Add a layout container and the Conversation component to the container.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    ...,
    {
        "operation": "insert",
        "name": "UsrConversationContainer",
        "values": {
            "type": "crt.FlexContainer",
            "direction": "column",
            "items": [],
            "fitContent": true,
            "alignItems": "stretch",
            "justifyContent": "start",
            "gap": "small",
            "wrap": "nowrap"
        },
        /* Name of the parent element on the page. */
        "parentName": "GeneralInfoTab",
        "propertyName": "items",
        "index": 0
    },
    {
        "operation": "insert",
        "name": "UsrConversation",
        "values": {
            "type": "crt.Conversation",
            /* Attribute that stores the messages. */
            "messages": "$UsrChatMessages",
            "conversationEvent": "$ConversationEvent",
            /* Turn off the automatic scrolling of the message feed.
            Users load the messages of previous chats using the "Load
            previous messages" button. */
            "disableAutoScroll": true,
            /* Without the "crt.MessageEditor" component in the
            "tools" property, the component shows the messages in
            read-only mode. */
            "tools": [],
            "actions": [],
            "information": [],
            "placeholder": [],
            "typing": []
        },
        "parentName": "UsrConversationContainer",
        "propertyName": "items",
        "index": 0
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Save the changes.

As a result, the page shows the Conversation component. The component shows the messages after you load them to the attribute.

2. Load the messages

The Conversation component shows the messages that are stored in the attribute bound to the messages property. Creatio supports the following ways to load messages:

Load the messages of a chat.
Load messages from a custom source.

Load the messages of a chat

Creatio loads the messages of a chat using the crt.LoadConversationRequest base request. Execute the request after the record of the page is loaded, that is, when the Id attribute changes. The request works for any record of the "Chat" (OmniChat code) object. In the "replace" mode, the request also writes the ID of the chat to the ChatId attribute. If the page has a ChatId attribute, Creatio overwrites its value. Customers might have several chats. To let users load the messages of previous chats of the customer, set up the Load previous messages button.

To load the messages of a chat:

Add the dependencies.

Add the @creatio-devkit/common library as a dependency.

Add the sdk argument.

Schema dependencies
define("UsrSomePage",
    /**SCHEMA_DEPS*/["@creatio-devkit/common"]/**SCHEMA_DEPS*/,
    function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
})

Set up the attribute of the previous chat (optional).

Go to the viewModelConfigDiff schema section.

Add the attribute that stores the ID of the previous chat.

viewModelConfigDiff schema section
viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "path": ["attributes"],
        "values": {
            /* ID of the previous chat. If the chat has no previous
            chats, Creatio sets the value to "null." */
            "UsrPreviousChatId": {
                "value": ""
            }
        }
    }
]/**SCHEMA_VIEW_MODEL_CONFIG_DIFF*/,

Add a request handler.

Go to the handlers schema section.

Add a custom implementation of the crt.HandleViewModelAttributeChangeRequest base request handler.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    ...,
    {
        request: "crt.HandleViewModelAttributeChangeRequest",
        /* The custom implementation of the base request handler. */
        handler: async (request, next) => {
            /* Load the messages when the record of the page is
            loaded. */
            if (request.attributeName === "Id") {
                /* Retrieve the instance of the handler chain service
                from "@creatio-devkit/common." */
                const handlerChain = sdk.HandlerChainService.instance;
                /* Send the base request to load the messages. */
                await handlerChain.process({
                    type: "crt.LoadConversationRequest",
                    /* ID of the chat. On the chat page, the ID of the
                    record. */
                    chatId: await request.$context["Id"],
                    /* Name of the attribute that stores the
                    messages. */
                    chatMessagesAttributeName: "UsrChatMessages",
                    /* Name of the attribute that stores the ID of
                    the previous chat. Specify it to set up the "Load
                    previous messages" button. */
                    previousChatIdAttributeName: "UsrPreviousChatId",
                    $context: request.$context
                });
            }
            /* Call the next handler if it exists and return its
            result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

Set up the Load previous messages button (optional).

Go to the viewConfigDiff schema section.

Bind the hasPreviousMessages property of the Conversation component to the attribute of the previous chat and set up the loadPreviousMessages property.

viewConfigDiff schema section
viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
    ...,
    {
        "operation": "merge",
        "name": "UsrConversation",
        "values": {
            /* Creatio shows the "Load previous messages" button if
            the attribute has a value. */
            "hasPreviousMessages": "$UsrPreviousChatId",
            "loadPreviousMessages": {
                "request": "crt.LoadConversationRequest",
                "params": {
                    /* Required parameter. In the "append" mode, Creatio
                    loads the messages of the chat whose ID is stored in
                    the attribute specified in the
                    "previousChatIdAttributeName" parameter. */
                    "chatId": "$Id",
                    "chatMessagesAttributeName": "UsrChatMessages",
                    "previousChatIdAttributeName": "UsrPreviousChatId",
                    /* Add the messages of the previous chat before
                    the current messages. */
                    "loadMode": "append"
                }
            }
        }
    }
]/**SCHEMA_VIEW_CONFIG_DIFF*/,

Save the changes.

As a result, the Conversation component shows the messages of the chat when the page opens and when a user switches to another record. For customers who have previous chats, the component shows the Load previous messages button. The button adds the messages of the previous chat before the current messages. After the earliest chat is loaded, Creatio hides the button.

Load messages from a custom source

To show messages that are not stored as chat messages in Creatio, load them to the attribute of the component using your own request handler. The handler must set the attribute to an array of messages in the UnifiedChatMessage format. For messages of the "text" type, also specify the message text in the text property. Learn more: Omnichannel inbox component.

To load messages from a custom source:

Add a request handler.

Go to the handlers schema section.

Add a custom implementation of the crt.HandleViewModelAttributeChangeRequest base request handler.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    ...,
    {
        request: "crt.HandleViewModelAttributeChangeRequest",
        /* The custom implementation of the base request handler. */
        handler: async (request, next) => {
            if (request.attributeName === "Id") {
                /* Retrieve the messages from the custom source. */
                const messages = [
                    {
                        id: "a6a3d8a4-6e0f-4a3d-9a3e-2f6b1c2d3e4f",
                        /* Message date of the "Date" type. */
                        date: new Date(),
                        author: {
                            id: "b7b4e9b5-7f10-4b4e-8b4f-3a7c2d3e4f50",
                            name: "John Best"
                        },
                        type: "text",
                        /* "1" is an incoming message, "2" is an
                        outgoing message. */
                        direction: 1,
                        isBotMessage: false,
                        /* Required for text messages. */
                        text: "Hello"
                    }
                ];
                /* Set the attribute to a new array. Sort the
                messages from the oldest to the newest. The component
                does not sort the messages. */
                request.$context.UsrChatMessages = messages;
            }
            /* Call the next handler if it exists and return its
            result. */
            return next?.handle(request);
        }
    }
]/**SCHEMA_HANDLERS*/,

The component does not add service messages, for example, "Chat started" or date dividers. The crt.LoadConversationRequest base request adds them for chat messages.

To show a message in a custom layout, set the type property of the message to a custom message type and register a Freedom UI component for this type. Learn more: Show chat messages in a custom layout.

Save the changes.

As a result, the Conversation component shows the messages from the custom source.

1. Add the Conversation component to a page​

2. Load the messages​

Load the messages of a chat​

Load messages from a custom source​

See also​

1. Add the Conversation component to a page

2. Load the messages

Load the messages of a chat

Load messages from a custom source

See also