Show chat.

The chat step allows the user to send chat messages to partners and read chat messages from partners.

Chat is primarily an asynchronous messaging capability, like email. It sends the messages synchronously, but then notifies the partner asynchronously. The chat pane will update in near real time, giving an almost instant messaging capability.

The chat view also show other events associated with the worker, to put chat messages in context.

Each chat message (and associated attachments) are sent to all other parties to the chat. Each party has their own copy of all the chat messages, held as worker events.

The chat can be configured with some configuration options.


If set to false, will create a new chat message using the following properties from the data parameter:

message Chat message
attachments List of attachments (as node references or as file info objects).
userName Name of user who created the message.
timestamp Point in time when chat was created.
connectionName Name of connection that created the event. This defaults to the name of the node indentified by the "channel" parameter (i.e. the calling channel).

When show is false, chat will examine the channel parameter (automatically added when calling between parties) to determine the sender. However, since in a multi-party chat the sender may be relaying chat from another party, the connection name may also be sent to identify the chat originator.

An additional getSharingDescription property is used to return a description of the sharing in the "content" property. This is used internally by the chat step type and should not otherwise be used at it may change between versions.


An array of objects which specify the other parties to the chat, or a single object.

Each object has two properties: role (to identify the party) and action (to identify the action to call on the party).

The action defaults to the same action as the caller's chat.

If passed as a single string, it is assumed to be the role.

This means that in a typical case, the role will simply identify the role of the other party. Assuming the caller's chat step has a name of "chat", the following are equivalent.

"role": [
"role": "respondent",
"action": "chat"
"role": "respondent"

The config property is named "role" to make is consistent with other steps when the simple form is used.

A role that ends in a wildcard means "all connections with a role that matches", e.g. "share.*" would match "share.1", "share.2" and "share.banana".

Title for the chat. Defaults to the name of the context node.

An object that controls the features available on the editor. See the Editor topic in the development guide for details. Leave blank for a basic editor (equivalent to {"nonbasic":false}). This can be useful to remove features from the chat.

Set to false to turn off the editor and just show a plain text box.

showActions Set to true to show worker actions on the chat page, too. This is useful if you run chat as the @display action, where it will replace the standard worker page.
dataReferenceAttachments Reference of data area in which chat attachments should be held. Defaults to "attachments".
eventType Event type. Can be of form reference/name. Defaults to "chat/Chat".

Name of an action that can be called to perform a notification that a new chat has arrived. This will be passed a data block with descriptioin, suppressUser and sender properties.

Description and suppressUser can be passed directly into the Notify step. The sender property can be used to build a title for the notification, e.g. "Chat from %{param:data.sender}".

If the notifyAction is not given, no notifications are created.


Set to true for "readonly" mode, in which the message and attachments areas are not shown and there is no submit button. Other fields remain as is.


Additional content to show at the top of the page. Works in the same way as content on the Form script type.


Lists the active connections for the chat. The list is above the chat, below the content.


List of event types to include in the chat. If omitted or zero length, all event types are included. If you use include, remember to include the eventType itself. May be event type references or reference/name.


List of event types to exclude in the chat. If omitted or zero length, no event types are excluded. May be event type references or reference/name.


Caption to show on the button. Defaults to "Send". If using chat as a notes area (no connection), this might more usefully be called "Save".


Whether to show the check for new messages button. Default is true.


If set to true, set the actionRequired indicator when a message is received, and unset it when the message is read. This is suitable for processes that are centred around a chat interaction.


If set to content, set the worker message to the content when a message is received, and unset it when the message is read.

The chat message is internally known as the "message" and is written to the event description. This is a different message, the worker message. In some configurations, setting the worker message produces a notification.

The show property can also be set in the data parameter. This allows remote calls to a chat step to send chat from the other party (removing the need for multiple steps).

When called with the request parameter getEvents=true, the step will return a list of events in the content element, and a count of events in the key element. If the passed-in parameter key equals the count of events, no content is generated. This is used by the chat step itself, to auto refresh the chat display.

Chat will return a state of "submit" when the user submits a chat, "cancel" when the user cancels (closes) the chat, and "success" when the chat is called without showing the UI. The chat will redisplay the chat on submit, and return to the redirect URL on cancel, so there is rarely need to respond to these states. If you do, be careful not to mess up the default actions.

Member Type List

Tab/SequenceWeightMember Type
Flow rules/flowRules

Set Tags

Tag List