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
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.
const result = await chat.availability();Returns
Resolves with PortalChatAvailability \| null.
close()
Ends the conversation.
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')).
chat.connect();disconnect()
Closes the live connection.
chat.disconnect();getConfig()
Reads the window's look and behaviour.
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.
const chatMessages = await chat.history();Returns
Resolves with an array of PortalChatMessage.
on()
A new message arrived. Returns an unsubscribe function.
const result = chat.on(event, callback);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | 'message' | Yes | The event to listen for. |
callback | (value: PortalChatMessage) => void | Yes | One message of a conversation. |
Returns
Returns () => void.
on()
The conversation changed (agent joined, closed, queue position). Returns an unsubscribe function.
const result = chat.on(event, callback);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | 'session' | Yes | The event to listen for. |
callback | (value: PortalChatSession) => void | Yes | A conversation between a visitor and the site's agents. |
Returns
Returns () => void.
on()
The connection state changed. Returns an unsubscribe function.
const result = chat.on(event, callback);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | 'state' | Yes | The event to listen for. |
callback | (value: PortalChatConnectionState) => void | Yes | The 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.
const result = chat.on(event, callback);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | 'typing' | Yes | The event to listen for. |
callback | (value: { name: string; until: number }) => void | Yes | Function called when it happens. |
Returns
Returns () => void.
rate()
Rate the finished conversation (1 to 5).
await chat.rate(rating, comment);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
rating | number | Yes | A rating from 1 to 5. |
comment | string | Yes | — |
Returns
Resolves when the call has completed.
resume()
Re-opens this visitor's open conversation, or resolves null when there is none.
const result = await chat.resume();Returns
Resolves with PortalChatSession \| null.
send()
Sends a visitor message.
const chatMessage = await chat.send(text);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
text | string | Yes | The text. |
Returns
Resolves with a PortalChatMessage: One message of a conversation.
start()
Opens a new conversation.
const chatSession = await chat.start(input);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
input | PortalChatStartInput | Yes | What 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)
const state = chat.state;typing()
Tell the agents the visitor is typing (at most one call every three seconds).
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
const channel = chatClientConfig.channel;onError()
Called when a chat call fails.
chatClientConfig.onError(error);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
error | PortalChatError | Yes | The error shape of chat calls (onError). |
onMessage()
Called for every new message.
chatClientConfig.onMessage(message);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
message | PortalChatMessage | Yes | One 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
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
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
const channel = chatMountOptions.channel;onError()
Called when a chat call fails.
chatMountOptions.onError(error);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
error | PortalChatError | Yes | The error shape of chat calls (onError). |
onMessage()
Called for every new message.
chatMountOptions.onMessage(message);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
message | PortalChatMessage | Yes | One message of a conversation. |
open
Open the window immediately.
Type: boolean
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
const openKey = chatMountOptions.openKey;origin
The chat origin. Optional: the page's Portal.url_key gives it.
Type: string
const origin = chatMountOptions.origin;widget
The handle mount() / show() return.
close()
Remove everything this call added to the page and end any live connection.
widget.close();window.Portal.chat
Portal.chat — live chat, visitor side.
createClient()
The data client, for a developer who paints their own window.
const chatClient = window.Portal.chat.createClient(config);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
config | PortalChatClientConfig | Yes | Options 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.
window.Portal.chat.hide();mount()
An in-page conversation panel inside container. Idempotent per container.
const chatMountHandle = await window.Portal.chat.mount(container, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
container | HTMLElement | Yes | An in-page conversation panel inside container. |
options | PortalChatMountOptions | No | Options 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.
const chatMountHandle = window.Portal.chat.preview(container, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
container | HTMLElement | null | Yes | The element to draw into. |
options | PortalChatPreviewOptions | Yes | Options 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.
const chatMountHandle = await window.Portal.chat.show(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | PortalChatMountOptions | No | Options 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.
| Name | Type | Required | Description |
|---|---|---|---|
channel | string | Yes | The channel's slug. |
PortalChatChannelAvailability
Whether a channel can be answered live now.
| Name | Type | Required | Description |
|---|---|---|---|
state | 'open' | 'unstaffed' | 'closed' | Yes | open: someone can answer now. unstaffed: nobody is online. closed: outside the channel's hours. |
online | number | Yes | Agents online. |
next_open | string | null | Yes | ISO time the channel next opens, or null. |
offline_mode | string | Yes | What happens to messages when no one is there (for example leave a message). |
offline_message | string | Yes | The text to show then. |
PortalChatConnectionState
The state of a chat client's live connection.
One of:
idleconnectinglivereconnectingoffline
PortalChatError
The error shape of chat calls (onError).
| Name | Type | Required | Description |
|---|---|---|---|
status | number | Yes | The HTTP status. |
code | string | Yes | A stable machine code. |
message | string | Yes | A human-readable message. |
PortalChatFieldMode
How a pre-chat form field is treated: hidden, shown but skippable, or mandatory.
One of:
offoptionalrequired
PortalChatMessage
One message of a conversation.
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | The message's id. |
session_id | number | Yes | The conversation it belongs to. |
sender_type | 'visitor' | 'agent' | 'system' | Yes | Who wrote it: the visitor, an agent, or the system (notices). |
agent | PortalChatPerson | null | Yes | The agent, for agent messages. |
content | string | Yes | The text. |
created_at | string | null | Yes | ISO time sent. |
PortalChatPerson
A person in a chat (an agent).
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | The person's id. |
display_name | string | Yes | The name shown in the chat. |
PortalChatPosition
A corner of the screen the chat launcher sits in.
One of:
bottom-rightbottom-lefttop-righttop-left
PortalChatPreviewOptions
Options of Portal.chat.preview().
| Name | Type | Required | Description |
|---|---|---|---|
settings | PortalChatPublicConfig | Yes | The look, supplied by the caller. Preview never fetches it. |
kind | 'widget' | 'inline' | No | A floating widget or an in-page panel. |
state | 'online' | 'offline' | 'off' | No | Which state of the demo to show. |
script | string[] | No | A scripted conversation to play, one line per message. |
PortalChatPublicConfig
The look and behaviour of the chat window, as configured in the dashboard.
| Name | Type | Required | Description |
|---|---|---|---|
active | boolean | Yes | False when chat is switched off for the site. |
channel | string | null | Yes | The channel's slug, or null for the default channel's original answer. |
channel_name | string | Yes | The channel's display name. |
title | string | Yes | Window title. |
subtitle | string | Yes | Window subtitle. |
welcome_message | string | Yes | The first message the visitor sees. |
offline_message | string | Yes | Text shown when nobody is available. |
input_placeholder | string | Yes | Placeholder of the message box. |
strings | Record<string, string> | Yes | The owner's own wording for some of the window's strings. |
launcher_shape | 'circle' | 'rounded' | 'pill' | Yes | Launcher button shape. |
launcher_size | 'small' | 'medium' | 'large' | Yes | Launcher button size. |
launcher_icon | string | Yes | Launcher icon name. |
use_custom_icon | boolean | Yes | True when an uploaded icon replaces the named one. |
icon_no_background | boolean | Yes | True when the custom icon is drawn without the button's background. |
icon_version | string | null | Yes | Version of the uploaded icon (cache buster). |
launcher_label | string | Yes | Text on the launcher (pill shape). |
launcher_attention | string | Yes | How the launcher draws attention. One of none, pulse, bounce, badge. |
launcher_shadow | 'none' | 'soft' | 'strong' | Yes | Launcher shadow strength. |
position | PortalChatPosition | Yes | Corner of the screen. |
offset_x | number | Yes | Distance from the side edge, in px. |
offset_y | number | Yes | Distance from the bottom/top edge, in px. |
mobile_position | 'inherit' | PortalChatPosition | Yes | Corner on small screens (inherit = same as position). |
hide_on_mobile | boolean | Yes | Hide the launcher on small screens. |
window_size | 'compact' | 'standard' | 'large' | Yes | Size of the open window. |
z_index | number | Yes | CSS z-index of the widget. |
color | string | Yes | Main colour (CSS colour). |
color_text | string | Yes | Text colour on the main colour. |
color_dark | string | Yes | Main colour used in the dark theme. |
theme | 'light' | 'dark' | 'auto' | Yes | Colour theme; auto follows the visitor's system. |
header_style | 'solid' | 'gradient' | Yes | Header background style. |
corner_radius | number | Yes | Corner radius in px. |
font | 'inherit' | 'system' | Yes | Use the page's font (inherit) or the system font. |
teaser_text | string | Yes | Text of the teaser bubble beside the launcher. |
teaser_delay_seconds | number | Yes | Seconds before the teaser appears. |
auto_open | 'never' | 'after_seconds' | 'on_scroll' | Yes | Whether the window opens by itself. |
auto_open_seconds | number | Yes | Seconds before auto-open (after_seconds). |
remember_dismissed_days | number | Yes | Days a dismissed widget stays quiet. |
show_agent_names | boolean | Yes | Show the agent's name on messages. |
show_agent_photos | boolean | Yes | Show the agent's photo. |
sound | boolean | Yes | Play a sound on new messages. |
prechat_name | PortalChatFieldMode | Yes | Pre-chat form: name field. |
prechat_email | PortalChatFieldMode | Yes | Pre-chat form: e-mail field. |
prechat_phone | PortalChatFieldMode | Yes | Pre-chat form: phone field. |
prechat_subject | PortalChatFieldMode | Yes | Pre-chat form: subject field. |
consent_text | string | Yes | Consent checkbox text; empty = no checkbox. |
consent_link | string | Yes | Link attached to the consent text (privacy policy). |
include_paths | string[] | Yes | Only show on paths matching one of these (empty = everywhere). |
exclude_paths | string[] | Yes | Never show on paths matching one of these. |
hide_when_offline | boolean | Yes | Hide the widget when nobody can answer. |
ask_rating | boolean | Yes | Ask the visitor to rate the conversation at the end. |
rating_prompt | string | Yes | The text of that rating question. |
realtime | object | Yes | Connection details of the live-message service, or null when polling is used. |
realtime.key | string | Yes | The key. |
realtime.host | string | Yes | — |
realtime.port | number | Yes | — |
realtime.scheme | string | Yes | — |
realtime.path | string | Yes | — |
PortalChatSession
A conversation between a visitor and the site's agents.
| Name | Type | Required | Description |
|---|---|---|---|
id | number | Yes | The conversation's id. |
status | 'open' | 'closed' | Yes | Whether the conversation is still open. |
visitor_name | string | null | Yes | The visitor's name. |
channel_id | number | null | Yes | The channel it runs in. |
agent | PortalChatPerson | null | Yes | The agent handling it, once one joined. |
offline | boolean | Yes | True when the visitor left a message nobody could answer live. |
queue_position | number | null | Yes | Place in line (1 = next), or null when not waiting in a line of more than one. |
created_at | string | null | Yes | ISO time started. |
last_message_at | string | null | Yes | ISO time of the latest message. |
PortalChatStartInput
What client.start() sends to open a conversation.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | No | The visitor's name. |
email | string | No | The visitor's e-mail. |
firstMessage | string | No | The visitor's first message. |
pageUrl | string | No | The page the chat was started on. |
phone | string | No | The visitor's phone. |
subject | string | No | The subject of the conversation. |
consent | boolean | No | True when the visitor ticked the consent box. |