@humany/widget-conversation v2.1.28-alpha.9
Widget Conversation API
The Widget Conversation API provides support for reading and writing to a conversational component inside a widget.
Explore the API
You can try out and watch the Conversation API in action by clicking the button below.
Keep in mind that this is for demonstration purposes only and may not be best practice.
We do not recommend binding functions to the Window
object.
Accessing the API
Inside a plugin, access the global instance of ConversationPlatform
by passing in the current Container
to the getInstance()
method. It will return a Promise
that is resolved to the ConversationPlatform
instance. On the instance, register a provider and pass in a 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.
Example
import { ConversationPlatform } from '@humany/widget-conversation';
const MyPlugin = async (container) => {
const platform = await ConversationPlatform.getInstance(container);
platform.registerProvider('my-chat', (conversation, component) => {
// start interacting with the conversation here
});
};
Writing to the conversation
When writing content to the conversation you will first need to create an Agent
object and then use its print()
function. Specify the type of entry to print and pass in the content.
print(content: object)
Returns a ConversationEntry
message that can be used to update and/or remove the content from the conversation at a later stage.
Example
const agent = conversation.createAgent();
const entry = agent.print('Lorem ipsum');
entry.update({
// ...
});
entry.remove();
Messages
Simple text message
Used to render plain text without HTML-formatting.
Example
// print user message
conversation.user.print('Lorem ipsum');
// print agent message
const agent = conversation.createAgent();
agent.print('Lorem ipsum');
Message with list of actions
Example of how to render a list with actions. Is only supported on Agent
and as 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. |
Example
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',
},
});
Message with a form
Example of how to render a form that can be handled by the conversation.form
event. Is only supported on Agent
and as system message.
Name | Type | Description |
---|---|---|
title | string | Title for the entry. |
body | string | Body content for the entry. Supports HTML. |
form | (FormBuilder) => void | A callback function for building the form. Refer to the @humany/widget-forms package for more information about FormBuilder . |
key | string | The key used to refer to the form when validating and submitting the form. |
Example
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',
});
},
});
Specify a sender name and/or avatar
To create an agent with a name and avatar use the createAgent
method on the conversation.
Example
const agent = conversation.createAgent({
name: 'Mr. Agent',
avatar: 'https://www.site.com/avatar.jpg',
});
agent.print({
title: 'I found the following invoices associated to your account:',
actions: {
action1: 'Action 1',
action2: 'Action 2',
action3: 'Action 3',
},
});
Writing system messages
In order to print a system message to the conversation you invoke the print
method on the conversation
. The print
method accepts the same arguments as on the Agent
.
Example
conversation.print('Lorem ipsum');
Loading/typing indicator
In many cases you will likely fetch data from an external resource before the content is written to the conversation. In this case 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.
In cases where you want to notify the user that the agent is currently typing, you should use the typing
function on Agent
.
Example
Loading
const done = conversation.loading();
// ...
done(); // remove loader
Typing indicator
const done = agent.typing();
// ...
done(); // remove loader
Reading from the conversation
The second parameter to your provider handler is a ComponentNode
instance representing the conversational component. On it you can read the component's properties and react to action emitted by the component.
Actions
The following actions are emitted from the conversational component.
Important: For default actions it is important 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.
conversation.user-typing
Is emitted when the user´s typing indicator is changed.
Name | Type | Description |
---|---|---|
textLength | number | The current text length of the user's message. |
conversation.user-submit
Is emitted when the user submits a message.
Name | Type | Description |
---|---|---|
text | string | The submitted text. |
conversation.action
Is emitted when the user clicks on an action.
Name | Type | Description |
---|---|---|
text | string | Key of the submitted action. |
conversation.form
Is emitted when the data of a form is changed.
Name | Type | Description |
---|---|---|
data | FormData | The form data. |
formKey | string | The unique key for the form. |
actionKey | string | The key of the form component responsible for the change. |
In order to subscribe to any of these actions you have access to the ComponentNodeController
. Below is an example how to subscribe to the conversation.form
action.
component.actions.watch('conversation.form', (input, next) => {
return next(input);
});
Submitting forms
In order 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);
});
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago