Conversation

The conversation panel of the chat history interface, available as client.workflows.conversation. Shows one thread at a time, where the user can read the messages and ask follow-up questions, or start a new thread.

Works with the history workflow (client.workflows.history): selecting a thread in the list loads it here, and a new thread started here shows up in the list. Each message is backed by a MessageItem workflow, which shares the options of this workflow.

Instance properties

`workflow.destroyed`

Whether the workflow is destroyed.

Type: boolean

`workflow.exhausted`

Whether no more older messages will be loaded, as the displayed messages reach the start of the thread, or a page failed to load.

Type: boolean

`workflow.messages`

The messages on display, oldest first.

Type: Object[]

`workflow.states`

The current states of the workflow, by field name, such as data. For debugging.

Type: Object

`workflow.status`

The status of the data: initial, loading, ready, or erroneous.

Type: string or undefined

`workflow.thread`

The thread record on display.

Type: Object or undefined

`workflow.threadId`

The ID of the thread on display, or being loaded. Absent for a new thread not yet created.

Type: string or undefined

`workflow.trackers`

The trackers of the workflow, which track impressions, viewables, and clicks of the rendered items.

Type: Object

`workflow.views`

The views of the workflow: the elements bound to it, by role.

Type: Object

Instance methods

`workflow.clearApi()`

Remove the API options set by useApi().

Returns this.

`workflow.clearDataProcessor()`

Remove the functions added by useDataProcessor().

Returns this.

`workflow.clearInteractions()`

Remove the interaction options set by useInteractions().

Returns this.

`workflow.clearLayouts()`

Remove the layout options set by useLayouts().

Returns this.

`workflow.clearPagination()`

Remove the pagination options set by usePagination().

Returns this.

`workflow.clearTrackers()`

Remove the tracker options set by useTrackers().

Returns this.

`workflow.delete()`

Delete the thread on display. The panel then starts a new thread.

Throws Error: If no thread is loaded.

`workflow.favorite([value])`

Add the thread on display to, or remove it from, the favorites.

Parameter	Type	Description
`value`	`boolean`	`true` to favorite, `false` to unfavorite. Default `true`. Optional.

Throws Error: If no thread is loaded.

`workflow.load(threadId, [options])`

Load a thread into the conversation panel, and mark it as read.

Parameter	Type	Description
`threadId`	`string`	The thread ID.
`options`	`Object`	Optional.
`options.force`	`boolean`	Reload even if the thread is already on display. Default `false`. Optional.

Returns this.

`workflow.new([options])`

Start a new thread, with no messages, ready to take the first question. Does nothing if the panel is already on a new thread with nothing asked.

Parameter	Type	Description
`options`	`Object`	Optional.
`options.force`	`boolean`	Reset even if the panel is already on a new thread. Default `false`. Optional.

Returns this.

`workflow.notifyViewUpdate(role, [state])`

Tell the workflow that a view of a role is rendered, when the view is rendered by your own code. Lifecycle events are emitted off the view of the main role.

Parameter	Type	Description
`role`	`string`	The role.
`state`	`Object`	The view state. Status defaults to `ready`. Optional.

Returns this.

`workflow.on(name, callback)`

Listen to an event.

Parameter	Type	Description
`name`	`string`	The event name, or `'*'` for all events.
`callback`	`function`	Called with `(data, meta)` on every event, where `meta` carries the event `name` and the timestamp `ts`.

Returns function: A function to remove the listener.

`workflow.once(name)`

Wait for the next occurrence of an event.

Parameter	Type	Description
`name`	`string`	The event name.

Returns Promise<{data: *, meta: Object}>: The event, with its data and meta.

`workflow.rename(title)`

Rename the thread on display.

Parameter	Type	Description
`title`	`string`	The new title.

Throws Error: If no thread is loaded.

`workflow.restart()`

Start a new session, discarding the data of the current one, along with any API call in progress.

Returns this.

`workflow.send(question)`

Ask a question in the thread on display, or, if no thread is loaded, start a new thread with it. The question shows right away, and the answer shows as it is generated.

Parameter	Type	Description
`question`	`string`	The question.

Returns this.

`workflow.subscribe()`

Subscribe to answer updates of the thread on display.

Throws Error: If no thread is loaded.

`workflow.unsubscribe()`

Unsubscribe from answer updates of the thread on display.

Throws Error: If no thread is loaded.

`workflow.updateData(data)`

Update the workflow with data from your own source, instead of calling the API. The data must carry the current session, or it is ignored.

Parameter	Type	Description
`data`	`Object`
`data.session`	`Object`	The current session, `workflow.session`.
`data.value`	`*`	The data value, in the shape of the API response. Optional.
`data.error`	`Object`	The error, if the data failed to load. Optional.

Returns this.

Throws Error: If data or its session is missing.

workflow.updateData({ session: workflow.session, value: response });

`workflow.useApi([name], [payload])`

Set the API to call, and extra payload to send with each request.

Parameter	Type	Description
`name`	`string` or `Object` or `false`	The API name, such as `'questions'`, or with its group, such as `'ask/questions'`. Pass the payload object alone to keep the API, or `false` to stop calling the API, so you can provide data by `updateData()` instead. Optional.
`payload`	`Object`	Extra payload, merged into the request payload. Optional.

Returns this.

workflow.useApi("ask/questions", { source_fl: ["title", "url"] });

`workflow.useDataProcessor(fns)`

Add functions to process the data before it is rendered. They run in the order they are added.

Parameter	Type	Description
`fns`	`function` or `function()[]`	Functions taking `(data, oldData)` and returning the processed data.

Returns this.

`workflow.useInteractions(options)`

Set how interactions are sent.

Parameter	Type	Description
`options`	`Object` or `false`	Pass `false` to stop sending interactions.
`options.preprocess`	`function` or `function()[]`	Functions taking the interaction payload and returning the modified one, run before it is sent. Optional.
`options.handle`	`function`	A function taking the interaction payload, to send it yourself instead. Optional.

Returns this.

`workflow.useLayouts(options)`

Set the layouts, by role.

Parameter	Type	Description
`options`	`Object` or `false`	The layout of each role, as a layout name, layout options, or `[name, options]`. Pass `false` to stop rendering.

Returns this.

workflow.useLayouts({
  query: { placeholder: "Ask a question" },
  products: "list",
});

`workflow.usePagination(options)`

Set the pagination options.

Parameter	Type	Description
`options`	`Object` or `boolean`	`true` or `false` to turn pagination on or off, or the options, such as `active` and `mode`.

Returns this.

`workflow.useTrackers(options)`

Set the trackers, by role.

Parameter	Type	Description
`options`	`Object` or `boolean`	`true` or `false` to turn all trackers on or off, or the options of each role: `active`, and the options of each event type, `impression`, `viewable` (`area` and `duration`), and `click` (`lenient`).

Returns this.

workflow.useTrackers({ products: { viewable: { duration: 2000 } } });

History

Reader type