Version: 8.3

Show chat messages in a custom layout

Level: advanced

note

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

Some chat messages might need a dedicated layout, for example, a product card or a summary of an order. Since version 8.3.3, you can register a custom Freedom UI component that shows messages of a specific type in the Conversation component. The Conversation component selects the Freedom UI component for each message by the type property of the message. To register a custom Freedom UI component for a custom message type, implement the component in a remote module and register it using the @CrtChatMessageType decorator. The Conversation component is a child component of the Omnichannel inbox component that shows the chats in the Agent Inbox panel. Learn more: Omnichannel inbox component.

To show chat messages in a custom layout, complete the following steps.

1. Create an Angular project

To create an Angular project to develop a component of the custom message type, follow the instructions: Create an Angular project.

2. Install npm packages

To install npm packages, follow the instructions: Install npm packages.

3. Create the message type component

For Creatio version 8.3.4 and later, ensure the project includes the "AGENTS.md" file. Instructions: Create a custom Freedom UI component (step 1).
For Creatio version 8.3.4 and later, run the ng g c features/runtime/view-elements/custom-message --view-encapsulation=ShadowDom command in the Visual Studio Code terminal to create an Angular component in the project.

Where:
- "features/runtime/view-elements" specifies that the Angular component is added to the runtime feature.
- custom-message is the custom component name.
This adds the component files to the "src/app/features/runtime/view-elements/custom-message" directory.

For Creatio version 8.3.3
Run the ng g c view-elements/custom-message --view-encapsulation=ShadowDom command in the Visual Studio Code terminal to create an Angular component in the project, where custom-message is the custom component name. This adds the component files to the "src/app/view-elements/custom-message" directory.
Specify that the CustomMessageComponent component is a chat message type.
1. Open the "custom-message.component.ts" file.
2. Flag the component using the @CrtChatMessageType decorator. The decorator maps the message type to the selector of the custom element. The decorator does not create the custom element.
  
  Creatio registers the mapping when it runs the code that declares the component class. For a remote module that loads at startup, that happens when the module loads. For a remote module in the deferred format, it happens when Creatio activates the feature that contains the component. If you specify an out-of-the-box message type, the custom element replaces the out-of-the-box layout of this type in every Conversation component. Messages that the component showed before the registration keep the out-of-the-box layout until the conversation is rendered again.
3. Import the required functionality from the libraries into the file.
4. Save the file.
  "custom-message.component.ts" file
```
/* Import the required functionality from the libraries. */
import { Component, Input, ViewEncapsulation } from '@angular/core';
import { CrtChatMessageType } from '@creatio-devkit/common';

@Component({
  selector: 'usr-custom-message',
  templateUrl: './custom-message.component.html',
  styleUrls: ['./custom-message.component.scss'],
  encapsulation: ViewEncapsulation.ShadowDom
})
/* Register the component as a chat message type. */
@CrtChatMessageType({
  /* Selector of the custom element. Must match the selector in the
  "customElements.define" call. */
  selector: 'usr-custom-message',
  /* Message type. Do not use the out-of-the-box types: "text,"
  "image," "file," "system," and "textWithButtons." Do not use the
  reserved "composite" type either. */
  messageType: 'usrCustom'
})
export class CustomMessageComponent {
}
```

4. Implement the business logic of the message type component

Open the "custom-message.component.ts" file.

Add the message input that receives the message in the UnifiedChatMessage format.

"custom-message.component.ts" file
...
export class CustomMessageComponent {
  /* Message in the "UnifiedChatMessage" format. The "Conversation"
  component also sets the "searchFilter" property of the element. */
  @Input()
  public message: any;
}

Save the file.

Add the markup of the message type component to the "custom-message.component.html" file.

"custom-message.component.html" file
<!-- Name of the message author. If several messages in a row have the same
author, the "author" property is empty for every message except the first.
-->
<div>{{ message?.author?.name }}</div>
<!-- Message text. -->
<div>{{ message?.text }}</div>

5. Register the message type component

For Creatio version 8.3.4 and later, register the CustomMessageComponent component in the runtime feature.

Open the "runtime.feature-activation.ts" file.
Define the CustomMessageComponent component as an Angular Element. Use the selector that you specified in the @CrtChatMessageType decorator. Learn more: Angular elements overview (official vendor documentation).

The ensureFeatureModuleRef() function is defined in the "remote-app-context.ts" file of the remote module template, not in the @creatio-devkit/common library. The first call to the function bootstraps the remote application, and later calls reuse it.
Save the file.

"runtime.feature-activation.ts" file
export async function activateRuntimeFeature(): Promise<void> {
  const moduleRef = await ensureFeatureModuleRef(RuntimeFeatureModule);

  /* Selector from the "@CrtChatMessageType" decorator. */
  if (!customElements.get('usr-custom-message')) {
    const element = createCustomElement(CustomMessageComponent, {
      injector: moduleRef.injector,
    });
    customElements.define('usr-custom-message', element);
  }
  ...
}

For Creatio version 8.3.3

Register the CustomMessageComponent component as an Angular Element.

Open the "app.module.ts" file.
Register the CustomMessageComponent component as an Angular Element in the ngDoBootstrap() method of the AppModule root module. Use the selector that you specified in the @CrtChatMessageType decorator. Learn more: Angular elements overview (official vendor documentation).
Save the file.

"app.module.ts" file
/* Import the required functionality from the libraries. */
import { DoBootstrap, Injector, NgModule } from '@angular/core';
import { createCustomElement } from '@angular/elements';
import { BrowserModule } from '@angular/platform-browser';
import {
  CustomMessageComponent
} from './view-elements/custom-message/custom-message.component';

@NgModule({
  declarations: [
    CustomMessageComponent
  ],
  imports: [BrowserModule],
  providers: [],
})
export class AppModule implements DoBootstrap {
  constructor(private _injector: Injector) {}

  ngDoBootstrap(): void {
    /* Register CustomMessageComponent as an Angular Element. Use the
    selector from the "@CrtChatMessageType" decorator. */
    const element = createCustomElement(CustomMessageComponent, {
      injector: this._injector,
    });
    customElements.define('usr-custom-message', element);
    ...
  }
}

Run the npm run build command in the Visual Studio Code terminal to build the project. This adds the build to the "dist" directory of the Angular project.
Repeat step 2 of the add the custom Freedom UI component to the Freedom UI page instructions to upload packages to Creatio using the Clio utility.

6. Add messages of the custom type

The Conversation component shows a message using the custom Freedom UI component if the type property of the message is set to the custom message type. The crt.LoadConversationRequest base request and the Agent Inbox panel load chat messages that have the out-of-the-box message types only. To show messages of the custom type, change the type of the messages in the attribute of the Conversation component using your own request handler.

To add messages of the custom type:

Add the Conversation component to the Freedom UI page. Instructions: Add the Conversation component to a page.

Implement the base request handler.

Go to the handlers schema section.

Add a custom implementation of the crt.LoadConversationRequest base request handler. In the handler, set the type property of the messages to the message type that you specified in the @CrtChatMessageType decorator.

handlers schema section
handlers: /**SCHEMA_HANDLERS*/[
    ...,
    {
        request: "crt.LoadConversationRequest",
        /* The custom implementation of the base request handler. */
        handler: async (request, next) => {
            /* Wait for Creatio to load the messages to the attribute. */
            const result = await next?.handle(request);
            const attributeName = request.chatMessagesAttributeName;
            const messages = await request.$context[attributeName];
            /* Set the attribute to a new array. Set the custom message
            type for the messages that need the custom layout, for
            example, for messages that start with "#order." */
            request.$context[attributeName] = messages.map((message) =>
                message.type === "text" && message.text?.startsWith("#order")
                    ? { ...message, type: "usrCustom" }
                    : message
            );
            return result;
        }
    }
]/**SCHEMA_HANDLERS*/,

Save the changes.

As a result, the Conversation component shows messages of the custom type using the custom Freedom UI component.

1. Create an Angular project​

2. Install npm packages​

3. Create the message type component​

4. Implement the business logic of the message type component​

5. Register the message type component​

6. Add messages of the custom type​

See also​