Widget Conversation API

The Widget Conversation API provides support for reading and writing to a conversational component inside a widget.

Sandbox

For demonstration purposes, we've set up a sandbox for the Widget Conversational API so that you can see it in action. Keep in mind that this is for demonstration purposes only and may not reflect best practice.

We do not recommend binding functions to the window object.

Accessing the API

In order to access the API you need to have a widget with a conversational component.

Creating the plugin

You need to register the conversational provider in the providers-property in the component. To access the global instance of ConversationPlatform, you pass in the current Container to the getInstance() method. It will return a Promise that is resolved to the ConversationPlatform instance. In the instance, register a provider and pass in name and handler by calling the registerProvider() function as shown below.

The handler function will be called once a conversational component for the specified provider is activated in the widget. Use the provider to interact with the conversation.

import { ConversationPlatform } from '@telia-ace/widget-conversation';

const MyPlugin = async (container) => {
    const platform = await ConversationPlatform.getInstance(container);

    platform.registerProvider('my-chat', (conversation, component) => {
        // start interacting with the conversation here
    });
};

You also need to register the provider inside the widget configuration:

   "my-conversation-component": {
        "type": "conversation",
        "properties": {
            "providers": ["my-chat"],
            // ...
        },
        "context": {}
    },

Creating an agent in the conversation

When using createAgent you can specify both a name and an avatar. These will then be displayed in the conversation alongside that agent's entries.

const agent = conversation.createAgent({
    name: 'Agent Smith',
    avatar: 'https://www.site.com/avatar.jpg',
});

Writing to the conversation

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.

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.

Example of simple text message

// print user message
conversation.user.print('Lorem ipsum');

// print agent message
const agent = conversation.createAgent();
agent.print('Lorem ipsum');

Example of updating or removing content

const agent = conversation.createAgent();
const entry = agent.print('Hello world!');

entry.update({
    // ...
});

entry.remove();

Entry with list of actions

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.

Example of a list of actions

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',
    },
});

Entry with a form

You can also post a message with a form attached. This uses the FormBuilder-method. This is handled by the conversation.form event. It is only supported for Agent and will be displayed as a system message.

Example of an entry with a form

agent.print({
    title: 'Log in',
    body: 'Enter your ID to login',
    key: 'my-login-form',
    form: (builder) => {
        builder
            .createComponent({
                component: 'Text',
                type: 'number',
                name: 'id',
                title: 'ID',
                required: true,
            })
            .createComponent({
                title: 'Log in',
                actionKey: 'submit',
                name: 'submit',
                component: 'Submit',
                type: 'submit',
                evaluate: true,
                value: 'Log in',
            });
    },
});

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.

When you need to make the user aware that your agent is currently typing, you should use the typing function on Agent.

Example of loading

const done = conversation.loading();
// ...
done(); // remove loader

Example of typing

const done = agent.typing();
// ...
done(); // remove loader

Writing system messages

System message in the conversation are sent by using the print method on the conversation. The print method accepts the same arguments as on the Agent.

Example

conversation.print('Hello world!');

Reading from the conversation

The second parameter to your provider handler is a ComponentNode instance representing the conversational component. From it you can read the component's properties and react to action emitted by the component.

The following actions are emitted from the conversational component:

For default actions it is necessary to call next() unless you want to completely stop the execution flow for the particular action. Not doing so will stop any succeeding handlers and may unintentionally break functionality.

If you want to subscribe to any of the conversation.form-actions you have access to the ComponentNodeController. Example below:

component.actions.watch('conversation.form', (input, next) => {
    return next(input);
});

Submitting forms

If you want to listen for form events you should subscribe to the conversation.form event. By passing a key to the form, you are able to target the form in this listener.

component.actions.watch('conversation.form', (input, next) => {
    if (input.formKey === 'my-login-form' && input.actionKey === 'submit') {
        const username = input.data.username;
        const password = input.data.password;
    }

    return next(input);
});

Adding custom list items

You can add custom list items to the conversation. To do so you have to register your own custom React component, which will be mapped to a key also provided by you.

Example of custom list items

import { registerCustomMessageComponent } from '@telia-ace/widget-conversation';

registerCustomMessageComponent(container, 'my-custom-list-item', import('./my-custom-list-item'));

Once the component has been registered it will be available to be used as any other item in the print method on the Conversation API.

Custom secondary action

You can add a secondary action button that's displayed next to the user input field. This button can run any event that you write. You need to add the secondaryAction property to the conversation component in the configuration. It accepts an object with the following properties:

    "conversation": {
        "type": "conversation",
        "properties": {
            "secondaryAction": {
                "action": "my-secondary-action",
                "label": "Label for the secondary action",
                "icon": "my-icon"
            }
            // ...other properties
        }
    }

When you have added this property to the component, you can create an event for it in your code:

component.actions.watch('conversation.action', (input, next) => {
    if (input === 'my-secondary-action') {
        // handle action
    }
});