Skip to content

Chat ​

Live chat, visitor side only: show the floating widget, mount an in-page panel, or drive the data client yourself.

Quick start ​

Show the floating widget

ts
await window.Portal.chat.show({ channel: 'support' });

API reference ​

chat ​

The chat data client, for a developer who paints their own window.

availability() ​

Whether this channel can be answered live now; null when the server cannot say.

ts
const result = await chat.availability();

Returns

Resolves with PortalChatAvailability \| null.

close() ​

Ends the conversation.

ts
const chatSession = await chat.close();

Returns

Resolves with a PortalChatSession: A conversation between a visitor and the site's agents.

connect() ​

Opens the live connection (messages arrive via on('message')).

ts
chat.connect();

disconnect() ​

Closes the live connection.

ts
chat.disconnect();

getConfig() ​

Reads the window's look and behaviour.

ts
const chatPublicConfig = await chat.getConfig();

Returns

Resolves with a PortalChatPublicConfig: The look and behaviour of the chat window, as configured in the dashboard.

history() ​

The messages of the conversation so far.

ts
const chatMessages = await chat.history();

Returns

Resolves with an array of PortalChatMessage.

on() ​

A new message arrived. Returns an unsubscribe function.

ts
const result = chat.on(event, callback);

Parameters

NameTypeRequiredDescription
event'message'YesThe event to listen for.
callback(value: PortalChatMessage) => voidYesOne message of a conversation.

Returns

Returns () => void.

on() ​

The conversation changed (agent joined, closed, queue position). Returns an unsubscribe function.

ts
const result = chat.on(event, callback);

Parameters

NameTypeRequiredDescription
event'session'YesThe event to listen for.
callback(value: PortalChatSession) => voidYesA conversation between a visitor and the site's agents.

Returns

Returns () => void.

on() ​

The connection state changed. Returns an unsubscribe function.

ts
const result = chat.on(event, callback);

Parameters

NameTypeRequiredDescription
event'state'YesThe event to listen for.
callback(value: PortalChatConnectionState) => voidYesThe state of a chat client's live connection.

Returns

Returns () => void.

on() ​

An agent is typing; until is the ms timestamp the indicator should vanish. Returns an unsubscribe function.

ts
const result = chat.on(event, callback);

Parameters

NameTypeRequiredDescription
event'typing'YesThe event to listen for.
callback(value: { name: string; until: number }) => voidYesFunction called when it happens.

Returns

Returns () => void.

rate() ​

Rate the finished conversation (1 to 5).

ts
await chat.rate(rating, comment);

Parameters

NameTypeRequiredDescription
ratingnumberYesA rating from 1 to 5.
commentstringYes—

Returns

Resolves when the call has completed.

resume() ​

Re-opens this visitor's open conversation, or resolves null when there is none.

ts
const result = await chat.resume();

Returns

Resolves with PortalChatSession \| null.

send() ​

Sends a visitor message.

ts
const chatMessage = await chat.send(text);

Parameters

NameTypeRequiredDescription
textstringYesThe text.

Returns

Resolves with a PortalChatMessage: One message of a conversation.

start() ​

Opens a new conversation.

ts
const chatSession = await chat.start(input);

Parameters

NameTypeRequiredDescription
inputPortalChatStartInputYesWhat client.start() sends to open a conversation.

Returns

Resolves with a PortalChatSession: A conversation between a visitor and the site's agents.

state ​

The state of the live connection.

Type: PortalChatConnectionState (read-only)

ts
const state = chat.state;

typing() ​

Tell the agents the visitor is typing (at most one call every three seconds).

ts
chat.typing();

PortalChatClientConfig ​

Options of Portal.chat.createClient().

channel ​

The channel's slug. Without it the default channel is shown. (The old widget and channelId options were removed.)

Type: string

ts
const channel = chatClientConfig.channel;

onError() ​

Called when a chat call fails.

ts
chatClientConfig.onError(error);

Parameters

NameTypeRequiredDescription
errorPortalChatErrorYesThe error shape of chat calls (onError).

onMessage() ​

Called for every new message.

ts
chatClientConfig.onMessage(message);

Parameters

NameTypeRequiredDescription
messagePortalChatMessageYesOne message of a conversation.

openKey ​

The open key of a Brain channel that answers any website (). Sent as X-Chat-Open-Key on every chat call.

Type: string

ts
const openKey = chatClientConfig.openKey;

origin ​

The chat origin, for example https://<ref>.sites.appfactory.studio. Optional: the page's Portal.url_key gives it.

Type: string

ts
const origin = chatClientConfig.origin;

PortalChatMountOptions ​

Options of Portal.chat.mount() and Portal.chat.show().

channel ​

The channel's slug. Without it the default channel is shown. (The old widget and channelId options were removed.)

Type: string

ts
const channel = chatMountOptions.channel;

onError() ​

Called when a chat call fails.

ts
chatMountOptions.onError(error);

Parameters

NameTypeRequiredDescription
errorPortalChatErrorYesThe error shape of chat calls (onError).

onMessage() ​

Called for every new message.

ts
chatMountOptions.onMessage(message);

Parameters

NameTypeRequiredDescription
messagePortalChatMessageYesOne message of a conversation.

open ​

Open the window immediately.

Type: boolean

ts
const open = chatMountOptions.open;

openKey ​

The open key of a Brain channel that answers any website (). Sent as X-Chat-Open-Key on every chat call.

Type: string

ts
const openKey = chatMountOptions.openKey;

origin ​

The chat origin. Optional: the page's Portal.url_key gives it.

Type: string

ts
const origin = chatMountOptions.origin;

widget ​

The handle mount() / show() return.

close() ​

Remove everything this call added to the page and end any live connection.

ts
widget.close();

window.Portal.chat ​

Portal.chat — live chat, visitor side.

createClient() ​

The data client, for a developer who paints their own window.

ts
const chatClient = window.Portal.chat.createClient(config);

Parameters

NameTypeRequiredDescription
configPortalChatClientConfigYesOptions of Portal.chat.createClient().

Returns

Returns a PortalChatClient: The chat data client, for a developer who paints their own window.

hide() ​

Remove the widget from this page.

ts
window.Portal.chat.hide();

mount() ​

An in-page conversation panel inside container. Idempotent per container.

ts
const chatMountHandle = await window.Portal.chat.mount(container, options);

Parameters

NameTypeRequiredDescription
containerHTMLElementYesAn in-page conversation panel inside container.
optionsPortalChatMountOptionsNoOptions of Portal.chat.mount() and Portal.chat.show().

Returns

Resolves with a PortalChatMountHandle: The handle mount() / show() return.

preview() ​

The same UI with a built-in demo client. Connects to nothing.

ts
const chatMountHandle = window.Portal.chat.preview(container, options);

Parameters

NameTypeRequiredDescription
containerHTMLElement | nullYesThe element to draw into.
optionsPortalChatPreviewOptionsYesOptions of Portal.chat.preview().

Returns

Returns a PortalChatMountHandle: The handle mount() / show() return.

show() ​

Show the floating widget on this page. Idempotent per page. Nothing shows until this is called.

ts
const chatMountHandle = await window.Portal.chat.show(options);

Parameters

NameTypeRequiredDescription
optionsPortalChatMountOptionsNoOptions of Portal.chat.mount() and Portal.chat.show().

Returns

Resolves with a PortalChatMountHandle: The handle mount() / show() return.

Types ​

PortalChatAvailability ​

A channel's availability together with the channel's slug.

Extends PortalChatChannelAvailability.

NameTypeRequiredDescription
channelstringYesThe channel's slug.

PortalChatChannelAvailability ​

Whether a channel can be answered live now.

NameTypeRequiredDescription
state'open' | 'unstaffed' | 'closed'Yesopen: someone can answer now. unstaffed: nobody is online. closed: outside the channel's hours.
onlinenumberYesAgents online.
next_openstring | nullYesISO time the channel next opens, or null.
offline_modestringYesWhat happens to messages when no one is there (for example leave a message).
offline_messagestringYesThe text to show then.

PortalChatConnectionState ​

The state of a chat client's live connection.

One of:

  • idle
  • connecting
  • live
  • reconnecting
  • offline

PortalChatError ​

The error shape of chat calls (onError).

NameTypeRequiredDescription
statusnumberYesThe HTTP status.
codestringYesA stable machine code.
messagestringYesA human-readable message.

PortalChatFieldMode ​

How a pre-chat form field is treated: hidden, shown but skippable, or mandatory.

One of:

  • off
  • optional
  • required

PortalChatMessage ​

One message of a conversation.

NameTypeRequiredDescription
idnumberYesThe message's id.
session_idnumberYesThe conversation it belongs to.
sender_type'visitor' | 'agent' | 'system'YesWho wrote it: the visitor, an agent, or the system (notices).
agentPortalChatPerson | nullYesThe agent, for agent messages.
contentstringYesThe text.
created_atstring | nullYesISO time sent.

PortalChatPerson ​

A person in a chat (an agent).

NameTypeRequiredDescription
idnumberYesThe person's id.
display_namestringYesThe name shown in the chat.

PortalChatPosition ​

A corner of the screen the chat launcher sits in.

One of:

  • bottom-right
  • bottom-left
  • top-right
  • top-left

PortalChatPreviewOptions ​

Options of Portal.chat.preview().

NameTypeRequiredDescription
settingsPortalChatPublicConfigYesThe look, supplied by the caller. Preview never fetches it.
kind'widget' | 'inline'NoA floating widget or an in-page panel.
state'online' | 'offline' | 'off'NoWhich state of the demo to show.
scriptstring[]NoA scripted conversation to play, one line per message.

PortalChatPublicConfig ​

The look and behaviour of the chat window, as configured in the dashboard.

NameTypeRequiredDescription
activebooleanYesFalse when chat is switched off for the site.
channelstring | nullYesThe channel's slug, or null for the default channel's original answer.
channel_namestringYesThe channel's display name.
titlestringYesWindow title.
subtitlestringYesWindow subtitle.
welcome_messagestringYesThe first message the visitor sees.
offline_messagestringYesText shown when nobody is available.
input_placeholderstringYesPlaceholder of the message box.
stringsRecord<string, string>YesThe owner's own wording for some of the window's strings.
launcher_shape'circle' | 'rounded' | 'pill'YesLauncher button shape.
launcher_size'small' | 'medium' | 'large'YesLauncher button size.
launcher_iconstringYesLauncher icon name.
use_custom_iconbooleanYesTrue when an uploaded icon replaces the named one.
icon_no_backgroundbooleanYesTrue when the custom icon is drawn without the button's background.
icon_versionstring | nullYesVersion of the uploaded icon (cache buster).
launcher_labelstringYesText on the launcher (pill shape).
launcher_attentionstringYesHow the launcher draws attention. One of none, pulse, bounce, badge.
launcher_shadow'none' | 'soft' | 'strong'YesLauncher shadow strength.
positionPortalChatPositionYesCorner of the screen.
offset_xnumberYesDistance from the side edge, in px.
offset_ynumberYesDistance from the bottom/top edge, in px.
mobile_position'inherit' | PortalChatPositionYesCorner on small screens (inherit = same as position).
hide_on_mobilebooleanYesHide the launcher on small screens.
window_size'compact' | 'standard' | 'large'YesSize of the open window.
z_indexnumberYesCSS z-index of the widget.
colorstringYesMain colour (CSS colour).
color_textstringYesText colour on the main colour.
color_darkstringYesMain colour used in the dark theme.
theme'light' | 'dark' | 'auto'YesColour theme; auto follows the visitor's system.
header_style'solid' | 'gradient'YesHeader background style.
corner_radiusnumberYesCorner radius in px.
font'inherit' | 'system'YesUse the page's font (inherit) or the system font.
teaser_textstringYesText of the teaser bubble beside the launcher.
teaser_delay_secondsnumberYesSeconds before the teaser appears.
auto_open'never' | 'after_seconds' | 'on_scroll'YesWhether the window opens by itself.
auto_open_secondsnumberYesSeconds before auto-open (after_seconds).
remember_dismissed_daysnumberYesDays a dismissed widget stays quiet.
show_agent_namesbooleanYesShow the agent's name on messages.
show_agent_photosbooleanYesShow the agent's photo.
soundbooleanYesPlay a sound on new messages.
prechat_namePortalChatFieldModeYesPre-chat form: name field.
prechat_emailPortalChatFieldModeYesPre-chat form: e-mail field.
prechat_phonePortalChatFieldModeYesPre-chat form: phone field.
prechat_subjectPortalChatFieldModeYesPre-chat form: subject field.
consent_textstringYesConsent checkbox text; empty = no checkbox.
consent_linkstringYesLink attached to the consent text (privacy policy).
include_pathsstring[]YesOnly show on paths matching one of these (empty = everywhere).
exclude_pathsstring[]YesNever show on paths matching one of these.
hide_when_offlinebooleanYesHide the widget when nobody can answer.
ask_ratingbooleanYesAsk the visitor to rate the conversation at the end.
rating_promptstringYesThe text of that rating question.
realtimeobjectYesConnection details of the live-message service, or null when polling is used.
realtime.keystringYesThe key.
realtime.hoststringYes—
realtime.portnumberYes—
realtime.schemestringYes—
realtime.pathstringYes—

PortalChatSession ​

A conversation between a visitor and the site's agents.

NameTypeRequiredDescription
idnumberYesThe conversation's id.
status'open' | 'closed'YesWhether the conversation is still open.
visitor_namestring | nullYesThe visitor's name.
channel_idnumber | nullYesThe channel it runs in.
agentPortalChatPerson | nullYesThe agent handling it, once one joined.
offlinebooleanYesTrue when the visitor left a message nobody could answer live.
queue_positionnumber | nullYesPlace in line (1 = next), or null when not waiting in a line of more than one.
created_atstring | nullYesISO time started.
last_message_atstring | nullYesISO time of the latest message.

PortalChatStartInput ​

What client.start() sends to open a conversation.

NameTypeRequiredDescription
namestringNoThe visitor's name.
emailstringNoThe visitor's e-mail.
firstMessagestringNoThe visitor's first message.
pageUrlstringNoThe page the chat was started on.
phonestringNoThe visitor's phone.
subjectstringNoThe subject of the conversation.
consentbooleanNoTrue when the visitor ticked the consent box.