@robono/messaging-web
v0.23.0
Published
Robono messaging for websites, using the shared Messenger design and customer authentication.
Readme
Robono Messaging for websites
Try the supplied interface
Open the browser example, or create and run the complete local example with one command:
npx --package @robono/server robono-messenger-example --startThe local example requires Node.js 22.12 or later. The default preview uses
fictional people and stores text only in the page.
For a real test connection, use robono-messenger-example --live, add your Robono
test key to its private .env, then run npm start in the generated folder.
The example's local login is for demonstration. Connect your actual login using
the hosted installer below before putting Messenger in your customer application.
Recommended hosted setup
Run npx --package @robono/server robono-messenger-install in your project. Follow the generated connection guide and supply your existing verified login. Robono hosts the communication services; your server only issues the short-lived user session and synchronizes permissions. See the server package's hosted guide.
import {mountHostedRobonoMessenger} from '@robono/messaging-web';
import {hostedRobonoTokenProvider} from '@robono/messaging';
const messenger = await mountHostedRobonoMessenger(document.querySelector('#chat')!, {
userId: session.userId,
tokenProvider: hostedRobonoTokenProvider({
tokenEndpoint: '/api/robono-token',
getAccessToken: () => session.getAccessToken(),
}),
companyName: 'Your company',
contacts,
});
try { await messenger.signOut(); }
finally { await session.signOut(); }Give the container a height. Keep one connection per signed-in account; sign out before switching users. The installer supplies a component that manages this lifecycle. Your company supplies contact names and avatars, and synchronizes current communication permissions from its server.
Desktop and narrow layouts
The complete Messenger uses the width of its own container. At 760 pixels or wider it shows the conversation list beside the open chat; narrow containers use the compact inbox/back flow. Resizing keeps the selected conversation and saved draft. Dialogs remain inside their pane, below its header.
Pass layout: 'compact' to retain compact navigation at every width, or
layout: 'split' to show both panes from 640 pixels. The default is 'auto'.
These options apply to mountHostedRobonoMessenger, mountRobonoMessenger and
the React WebMessenger component. Give the container a height; no fixed browser
width or separate mobile integration is required.
Change one part of the interface
Choose fonts, text size, message spacing and bubble shape in Features & preview →
Appearance. The same saved appearance.presentation settings reach the preview
and supplied UI. See the customization guide
for exact options, defaults and the code equivalent.
Pass components to the mount function or React screen. MessageBody wraps or
replaces the inner content, MessageFooter adds content inside the bubble, and
HeaderActions adds an action beside the contact. Define these components outside
render so they retain their identity. All are optional; the supplied design is
unchanged when omitted.
import type {MessagingCustomization} from '@robono/messaging-web';
const components: MessagingCustomization = {
MessageBody: ({children}) => <div className="customer-message">{children}</div>,
HeaderActions: ({contact}) => (
<button type="button" onClick={() => openCustomerProfile(contact)}>
Profile
</button>
),
};
// Add components to mountHostedRobonoMessenger(..., { ...options, components }).MessageBody receives the supplied body as children. Retain it to keep text,
attachment playback, polls and translation results. The outer status indicator,
swipe gestures, quote, reaction and error handling remain supplied by Robono.
Message regions receive message, mine, appearance and optional pendingStatus.
Header actions receive conversationId, contact and appearance. Regions are
not called for deleted message bodies. Use accessible controls and do not inject
untrusted HTML. A custom action still needs your own authorization; a visual
customization does not change what the user is allowed to do.
Embed the Robono conversation screen in your website, using your own signed-in users, contacts and permissions. React Native Web and the shared Robono interface are bundled; consumers do not need native packages or bundler aliases.
npm install @robono/messaging-web @robono/messaging react react-domUse React 18.2 or 19 with the same React DOM version. The package is ESM and targets modern browsers with HTTPS, crypto.randomUUID, Fetch and native dialogs. Recording also needs MediaRecorder and microphone permission. Browser camera capture and available media codecs differ by device.
Connected features
The complete messenger connects selected calling, chat weather/tracking and Maps through Robono’s authenticated hosted connection. Customers do not supply fake demo callbacks or create separate call controllers for this setup. Feature selection and appearance remain in Features & preview. Advanced custom interfaces can still use individual components and callbacks.
Synchronize permitted contacts once on your server:
await messenger.synchronizeContact({
externalUserIds: [firstUserId, secondUserId],
allowed: currentPermission,
revision: savedPermissionRevision,
});This atomically updates texting and calling permission. It does not buy a service, start a call or start location tracking. Use a saved, increasing revision from your own database; retries with the same values are safe. Keep group membership in the messaging group API; eligible groups use that same membership for calls. Supergroups never start calls, and voice/video calls remain limited to eight people.
For the optional self-hosted connection, the host's authorize function checks calling.*, extras.* and location.* as
well as messaging operations. Account checks have no conversation ID; call actions
use the actual conversation from the service, never a caller-supplied claim. Keep
current membership, suspension and feature restrictions in those checks.
Incoming calls use the same configured notification providers as messages. The supplied client registers its call handler automatically. Native apps need their own Apple APNs key/bundle ID and Google Firebase service account; upload them only to Robono's private notification setup. A website needs its HTTPS origin and chat path, not Apple/Google keys. Users still choose whether to allow notifications. These are ordinary app/browser alerts: the OS can delay or suppress them, and an alert never answers a call or turns on a microphone automatically.
Await the returned signOut() before ending your own login session. It stops
capture and calls, cancels unfinished tracking and unregisters the device. Old
account credentials and unfinished work must never be reused for another person.
Optional self-hosted connection
The examples below are for customers who deliberately choose to run the forwarding adapter themselves. They are not required for the hosted setup.
Complete chat list
Use mountRobonoMessenger when the website should include the chat list, unread counts, and navigation into each conversation:
import {mountRobonoMessenger} from '@robono/messaging-web';
const messenger = mountRobonoMessenger(document.querySelector('#chat')!, {
endpoint: '/api/robono',
companyName: 'Your company',
userId: session.userId,
getAccessToken: () => session.getAccessToken(),
contacts: {bob: {name: 'Bob', avatarUrl: bobPhoto}},
});
// On logout:
try { await messenger.signOut(); }
finally { await session.signOut(); }The element needs a height, for example height: 650px. The server supplies authorized conversations and unread counts; contacts supplies display names and optional avatars. The React equivalent is WebMessenger with a MessagingInboxClient. Use mountRobonoChat if your application already has its own chat list.
Your server's authorize callback must allow conversations for the signed-in account. The adapter then calls that callback with operation: 'list' and each returned conversationId, so a locally revoked chat cannot appear while a membership update is in transit. Private unread counts clear only when a received message is visible. Turning off public read receipts does not disable these private counts.
Search is under Contact options → Search this chat. It opens an inline search bar with previous/next matches while keeping the conversation visible. It searches retained text in that conversation, including older pages, while respecting group join history. In Features & preview, Someone is typing and Online now are optional and off by default. Typing describes the current conversation; Online now describes foreground activity across the connected app. Optional Last seen stores the latest activity timestamp. Hiding the browser tab stops updates. Typing expires within five seconds and online activity within 45 seconds if a connection disappears without a stop message. See the activity guide.
This setup requires @robono/messaging and @robono/messaging-web 0.3.0 plus @robono/server 0.16.0. The corresponding messaging migrations and handlers must be deployed. Older 0.1.0 packages do not include these helpers.
Self-hosted authentication and backend
The browser sends your user's access token to your backend. Keep your Robono API key exclusively on that server. Install @robono/server there and mount these adapters as POST endpoints:
import {
RobonoMessagingBackend, RobonoManagedMedia,
createMessagingBackendAdapter, createMessagingMediaBackendAdapter,
} from '@robono/server';
const robono = new RobonoMessagingBackend({apiKey: process.env.ROBONO_API_KEY!});
const storage = new RobonoManagedMedia({apiKey: process.env.ROBONO_API_KEY!});
export const messages = createMessagingBackendAdapter({
robono,
// Verify the session, expiry and account status; return your stable user ID.
authenticate: request => sessions.authenticate(request),
// Check current conversation membership and any additional app restrictions.
authorize: ({actorId, operation, input}) =>
permissions.messaging(actorId, operation, input.conversationId),
resolveMedia: input => storage.resolve(input),
});
export const media = createMessagingMediaBackendAdapter({
robono, storage,
authenticate: request => sessions.authenticate(request),
authorize: ({actorId, operation, conversationId, uploadId}) =>
permissions.media(actorId, operation, conversationId, uploadId),
});
// Mount messages at /api/messaging and media at /api/media in your framework.sessions and permissions above represent your existing services. Never trust a browser-supplied user ID for authorization; the adapter replaces it with the verified session identity. Authorize history, reports and unblocking independently from permission to send. Verify ownership for unsent-upload discard requests. Robono also checks current membership and saved feature permissions on each operation.
Create direct conversations on your server with robono.setRelationship({externalUserIds: [userA, userB], allowed: true, revision}). Create groups with robono.setGroup({externalGroupId, name, allowed: true, revision, members: [{userId, canSend: true}, ...]}). Store the returned conversationId; persist increasing revisions when permissions or membership change. Users only receive conversation IDs they may access. Standard messaging groups support up to 250 members when enabled in the workspace; calling has separate limits. Supergroups support up to 2,000 members when Allow supergroups is selected in Features & preview. Use supergroup: true with group snapshots; member lists are paged and individual read receipts are omitted.
Enable Messaging and the desired message types in the Robono workspace. Enable managed attachment storage for the storage example above, or use your own implementation of the server media-storage contract. Configure allowed formats, sizes, voice duration and retention there.
React
Create one client per signed-in user, and keep transport functions stable. For example, in your authenticated chat route:
import {useEffect, useMemo, useState} from 'react';
import type {MessagingClient} from '@robono/messaging';
import {
createWebMessagingClient, createWebMessagingTransport, WebMessagingScreen,
} from '@robono/messaging-web';
type ChatProps = {
userId: string; conversationId: string;
getAccessToken: () => Promise<string>;
contact: {name: string; avatarUrl?: string};
};
export function Chat({userId, conversationId, getAccessToken, contact}: ChatProps) {
const [client, setClient] = useState<MessagingClient | null>(null);
useEffect(() => {
const next = createWebMessagingClient({
userId, url: '/api/messaging', getAccessToken,
});
setClient(next);
return () => next.dispose();
}, [userId, getAccessToken]);
const mediaRequest = useMemo(() => createWebMessagingTransport({
url: '/api/media', getAccessToken, requestTimeoutMs: 120000,
}), [getAccessToken]);
useEffect(() => {
if (client) void client.open(conversationId).catch(console.error);
}, [client, conversationId]);
return client && <WebMessagingScreen
client={client} userId={userId} contact={contact}
mediaRequest={mediaRequest} style={{height: '70dvh'}}
/>;
}Pass participants={{[userId]: {name, avatarUrl}}} for friendly group sender names. Saved appearance settings apply automatically; an appearance prop can override the presentation. onBack, onContactOptions and onMessageOptions connect to your navigation. A custom contact-options handler replaces the default menu, so include your required safety actions when overriding it.
The screen owns updates while mounted: it stops in hidden tabs or offline and refreshes on return. Set active={false} when your router covers the screen without unmounting it. Mount only one screen per client. On logout, await client.signOut(), then revoke your user session. Use client.dispose() when leaving a screen without signing out.
The supplied messenger saves outgoing messages, text drafts and selected photos/videos/files on this browser using IndexedDB. Reopening first checks current conversation access, then restores unsent messages with Retry. Retry keeps the original message ID so an interrupted response cannot create a second message. Sign-out and revoked access clear local saved content. Received history, credentials and download links are never saved by this outbox. Browser storage can be cleared by the user or browser; it is not a server backup. If storage fails, sending shows a recoverable error instead of silently claiming the message was saved. Use persistence: false to disable saving, or persistence: {namespace: yourTenantId} when the same endpoint/user ID spans multiple tenants.
For server-rendered frameworks, mount the chat in a client component after sign-in. Next.js integrations can use dynamic(() => import('./Chat'), {ssr: false}) inside a client component. Do not open network conversations while rendering on the server.
Other website frameworks
Use the imperative mount in a Vue, Angular, Svelte or plain JavaScript component. React and React DOM are still runtime dependencies; you do not need to convert the host page to React.
import {createWebMessagingClient, mountWebMessaging} from '@robono/messaging-web';
const client = createWebMessagingClient({
userId, url: '/api/messaging', getAccessToken,
});
await client.open(conversationId);
const chat = mountWebMessaging(document.querySelector('#chat')!, {
client, userId, contact: {name: 'Support'},
});
// When host properties change: chat.update({...allCurrentProps});
// When navigating away:
chat.unmount();
client.dispose();
// On logout instead: await client.signOut(); then revoke your session.Media, permissions and lifecycle
Supply mediaRequest to enable browser recording, file selection, upload review, private download and playback. Without it, use text, polls and reactions; media controls requiring a device adapter are unavailable. Voice recording requires an explicit click and browser permission. It stops at the network's duration limit; switching tabs interrupts recording into review. No recording is sent automatically. Recorded format is selected from browser-supported WebM/Opus or MP4 formats, and playback requires receiving-browser codec support.
File pickers follow the network's MIME and size rules. The server independently verifies uploaded bytes. Only opaque asset IDs enter messages; signed transfer URLs are temporary. Uploads and complete-file downloads omit user-session credentials and disallow redirects. Managed voice/video playback uses an authorized short-lived HTTPS URL directly in the browser player; allow the private media gateway in media-src as well as connect-src. The gateway must support CORS and byte ranges. Private stores requiring custom headers use the bounded download path. Never redirect private media URLs to another host. Owned object URLs, streams and downloads are cleaned up when switching conversations or unmounting. Do not persist download grants or add session tokens to storage URLs.
Same-origin endpoint paths are recommended. Cross-origin customer backends must allow the website's origin and its Authorization/Content-Type headers; signed storage endpoints need their own upload/download CORS configuration. Use HTTPS in production; HTTP is accepted only for local development. Keep broad host CSS selectors from overriding chat controls. The shared renderer injects styles, so a strict Content Security Policy must support its style strategy, blob: image/media previews and approved storage connections. Test the deployed site's CSP and browser permission settings.
This package includes the inbox and conversation interface. Your website supplies signed-in users and contact display information; the server supplies authorized chats. Open conversations use live updates when the service advertises them, with polling as a fallback. Background browser notifications are included through the combined server route; see Browser notifications below for website setup and browser limitations. Live calling is connected through the separate calling package. Website usage reports as platform web.
Working example and API
The repository's examples/messaging-web contains a runnable Vite website and Node backend with two local demo identities. It uses real Robono conversation and media APIs. Replace the demo password sign-in with your authentication before production use.
- Guide: https://robono.com/docs#messaging-web
- API reference: https://robono.com/sdk-reference/messaging-web/
- Support: https://robono.com/contact?topic=sdk
The Robono SDK license is in LICENSE. Bundled open-source dependencies retain their licenses in licenses/THIRD_PARTY_NOTICES.txt; SBOM.spdx.json inventories the distributed files and bundled packages.
November 1 behavior update
The shared conversation keeps photo captions on their attachment, preserves selection order, provides centered poll/Yes-No dialogs, and offers retry for older history. Enter sends; Shift+Enter inserts a newline. Photo selection creates a removable thumbnail; tapping it previews without sending. A received photo has Download and (where supported by the browser) Share. Tapping the viewed photo expands it; pinch/pan and Close remain available.
Voice recordings remain local until Send, including persistent browser drafts.
appearance.showWaveform hides the visual waveform without removing the stored
samples. Core bubble padding is fixed, rather than a customer layout option.
This is source work, not a new registry release. See
docs/operations/messaging-parity-2026-11-01.md in the source repository for the
comparison, deployment prerequisites and unresolved gaps.
Message translation
With message translation enabled and MessagingClient.transformRequest connected to
your authenticated createMessagingTransformBackendAdapter, the supplied screen
lets the viewer translate incoming text or voice using a saved conversation preference.
Open the header's three-dot menu and choose Off / Text / Voice, incoming language
and target language once. Translation defaults to Off. Translate / Play Translation
then acts directly, without another choice popup. Show original restores the source;
Show translation reuses the existing result. Own messages and matching known languages
do not show Translate. Transcription is a separate voice-message action.
language supplies the initial target; contact.language and
participants[id].language supply known sender languages. Unknown sender languages
use the conversation's saved incoming-language choice. This is not automatic language
detection. The standard browser client persists choices per endpoint/account/chat in
IndexedDB on this device. Custom menus can call client.setTranslationPreference.
Only an explicit message action processes content; saving preferences does not translate
history or incur processing usage. Use the current server adapter for voice output.
Optional downloads
In Features & preview → Appearance, select Download button to show Download
when a viewer opens a photo, video or file. The same setting is
appearance.showDownloadButton (default false). It saves the authorized file
already opened in the viewer, with its original filename. This is a display option;
the viewer still retrieves private media through the authenticated media adapter.
Saved, selection and bounded previews
The standard client includes Saved using IndexedDB, isolated by origin, endpoint, account and persistence namespace. Save makes an explicit private copy of the text/file after fresh access checks. The separate Messages menu opens Saved across all conversations; copies survive reload independently of network retention. client.signOut() clears the account’s copies, and persistence: false disables Saved. This is browser storage, not an encrypted or cloud backup. Multi-selection uses the same compact action bar as the native component; forwarding follows message order rather than selection order.
After the updated managed storage worker/inspector/media handler and migration 178 are deployed, new image/video uploads provide authenticated JPEG previews capped at 480 pixels and 128 KiB. Preview storage and delivery count toward quotas and charges. Large older uploads without previews stay tap-to-open: the SDK does not automatically download originals over 2 MiB to make a preview.
Social previews and calling
The updated messaging endpoint and server adapter enable the compact social-preview action automatically. Links still open the original app/site; the separate play action opens the shared app-height popup. Receiving a link does not load a third-party player. Supported providers include YouTube, Facebook, Instagram, TikTok, X, Snapchat, Rumble, Vimeo, Dailymotion, Reddit, Twitch, Pinterest, Threads, Bluesky, Spotify, SoundCloud and Telegram. A private, removed or provider-restricted post may require opening the original. Provider availability and sign-in requirements remain outside Robono's control.
Server access is checked before and after resolving a preview. The social.opened usage event is recorded for the requesting account; retries with the same event ID are counted once. An older server adapter hides the preview action. Third-party markup runs in an isolated frame at https://robono.com/messaging-embed.html; its scripts cannot read the customer page or its storage. You may self-host that file using socialEmbedPageUrl, retaining its sandbox/security headers. Keep host-page scripts restricted. Permit the renderer and the selected providers in your site's frame-src policy; Robono's website .htaccess contains the maintained provider list. YouTube and Twitch receive the hosting site's actual origin/domain.
Pass calling: {voice: conversationId => startVoiceCall(conversationId), video: conversationId => startVideoCall(conversationId)} to show the existing Messenger header buttons. Supply only the eligible callbacks. Your calling controller still performs admission and opens its call screen; these callbacks do not implement a calling service or bypass permissions. unansweredCallId and dismissUnansweredCall connect the reviewed voice/video-message offer after an unanswered outgoing call. The supplied browser adapter records a new video with the camera and microphone over HTTPS. Callers can play their draft, record again, cancel, or explicitly send it to the chat. Recording/review stays local; upload begins only on Send. Camera denial, cancellation, leaving the page and recording limits stop camera and microphone capture. Enable the optional offer in the website’s Calling options; the backend rechecks eligibility and permissions before recording and sending.
Playback and compact media controls
Opening a video starts playback when the browser allows it; if autoplay is blocked, the same player offers Play. Full screen, seeking, close and the optional download control use the shared viewer. Managed voice/video can start from a short-lived private media link without waiting for the complete file. If the link expires, the adapter obtains a newly authorized copy and preserves the current position and paused/playing state. Download and Share obtain a checked local copy without replacing the stream. The top action row fits narrow phone screens.
The shared viewer offers Download, Delete, Forward, Share and Close, subject to permissions. There is no external-player Open action. Recent original photos and voice clips may preload through the authenticated adapter: at most six files, 2 MiB each and 6 MiB total, with two concurrent transfers and a 60-second access window. The cache clears on backgrounding, conversation/account changes or access revocation. Set preloadRecentMedia={false} on the single-chat or complete Messenger to keep original transfers on demand. Warm voice clips reuse the authorized original; cold streams never wait for speculative preloading. Download and Share always obtain fresh access.
Company, account and call controls
companyName is the customer’s company name, not Robono’s. It labels the inbox
only; when omitted, the configured appearance name is used. Conversation screens
show only the friend/group header, never the company heading or account menu.
The main three-dot dropdown contains Account and Saved. Supply account with
name, optional avatarUrl, phone, and email. onEditProfile and onSignOut
are optional host actions; unsupported actions are hidden. Sign-out must revoke
your app session and call the messaging client’s signOut() to clear local data.
The Account screen dismisses before opening the host’s profile/sign-out flow.
Direct conversations keep the customer’s accent header. Groups use Messenger’s
blue #1F5F7A header with light text and icons. Phone/video icons use the same ink.
Supply contact.phoneNumber (or the inbox contact directory’s phoneNumber)
for carrier calls. Supply calling.voice/video only when that conversation is
eligible, and optionally calling.phone(number) to override the browser’s tel:
handler. calling.voiceLabel changes the internet-call label if needed. The phone
button offers available methods when a number exists; without a number it starts
the available internet call directly. Groups never offer a carrier call. The host’s
calling service still enforces call permissions and handles the call screen.
Browser notifications
With server 0.18.0 and website messenger 0.4.0, mountRobonoMessenger connects browser alerts automatically when endpoint points to your same-origin combined route. In Robono → Your app → Message notifications, enter your website origin and chat path. Users choose Enable notifications under Account; no prompt appears on mount. No Firebase/Apple private key is required for the website. iPhone needs an installed Home Screen web app.
Use HTTPS, preserve the route’s Service-Worker-Allowed header, and allow same-origin service workers in your content security policy. The dedicated /robono-notifications/ scope must be available. Your existing site-wide worker remains in place. Await the mounted messenger’s signOut() before ending the host session; dispose it on unmount. notifications:false opts out of automatic setup.
Custom interfaces can use connectBrowserMessagingNotifications with the same endpoint, signed-in user, access-token function, and current-access/open callbacks. This connector does not grant permission to read a chat. Never put a Robono network key in the browser. See the server package’s NOTIFICATIONS.md for full setup and platform limitations.
Send later
Hold Send, right-click it, or focus it and press Shift+F10 after composing a message to choose a scheduled time. The chat's three-dot menu contains Scheduled messages for sender-only rescheduling/cancellation. The service must advertise scheduling availability. The server sends independently of the browser; it rechecks current permissions, rules, screening and budgets. Times display in the browser's local time zone. The core messaging README lists queue limits, timing and retention.
Updating contacts without restarting (0.6+)
Call chat.updateContacts(currentContacts) on the handle returned by mountRobonoMessenger. This updates the inbox, current contact name and avatars while preserving the open conversation and draft. Changing accounts requires signing out the old handle and creating a new one; never change the identity behind its token callback. signOut() clears visible/local chat immediately and waits for notification cleanup. For automatic account events, use the connected templates generated by robono-messenger-install in server 0.20+.
Business messages
Use createMessageCard from @robono/messaging for supplied appointment/order
cards. components.customMessages supports customer layouts and explicit format
versions; components.onCustomMessageAction connects authorized actions.
Unknown types use the required text fallback.
Card setup and limits.
App-wide activity
The complete Messenger connection supplies foreground activity independently of
the selected chat. Online now and optional Last seen are chosen in Features &
preview. connection.availability can also supply an authorized contact list.
Activity setup, privacy and timing.
Recording, captions and local call tools
Robono hosts optional call recording and transcription. Enable recording once in the existing Calling settings; every participant must agree before capture, and anyone can stop it. The supplied controls include the consent notice, active-recording status and captions. No customer recording server is required.
The supplied adapters also offer camera/microphone/speaker checks and camera background blur. Screen sharing is separate. Phone blur requires rebuilding the native app; browser blur downloads its model only when selected and needs the documented content-security policy. Background processing stays on the device.
See the recording and call tools guide for prices, retention, short-lived downloads, deletion, platform requirements and label customization. Captions arrive in short batches with several seconds of delay and can be inaccurate; incomplete transcripts are marked.
Host navigation and private downloads
Both mountRobonoChat and mountRobonoMessenger accept linkHandling and
onDownloadAttachment. Set webLinks/addresses false for plain text, or supply
openUrl(url,message) / openAddress(address,message) to route navigation through
your app. Their returned handles expose updateHostControls() for permission
changes. The Download callback receives {file,message,signal} with a freshly
authorized browser File; enable appearance.showDownloadButton to show it.
When a callback is supplied, the SDK does not also trigger a browser download.
The complete Messenger also supports onNewConversation and inboxOverlay for
your own contact picker. MessagingPopup is exported for a picker that follows
the supplied Messenger's popup boundaries and design.
Shared sign-in presentation
The optional MessagingSignIn, MessagingPhoneInput and MessagingChoicePicker
exports use the same implementation as the phone SDK and Robono's new consumer
app. Keep your existing login when adding Messenger to a signed-in website.
These components provide presentation only: your authentication provider still
owns identity checks, verification, expiry, sessions and permission decisions.
Set company branding/colors with appearance or a logo React element, provide
your own consent copy/policy links, and override labels for your language.
Control stage, phone/code/name values, busy, disabled, error and
onSubmit from your application. Place the country field and its choice picker
inside phoneField, and additional profile inputs inside profileFields, so
pickers remain bounded to the embedded sign-in area. Desktop cards have a
480-pixel maximum width; phone layouts use the available width and scroll when
needed. No Robono account or Robono legal wording is imposed on your users.
MessagingConnectionState is the shared waiting/recovery screen used by the
customer starters and Robono Messenger. Pass error, onRetry, optional
onSignOut, appearance, and translated labels. Account actions appear only
on failure, never while a normal connection is opening.
The hosted connection now selects an approved direct transport automatically.
For a restrictive website Content Security Policy, allow the origin of the
server-issued transportEndpoint in connect-src. directTransport: false
keeps public-address routing when that policy cannot be changed. Authentication
and origin checks are identical on both routes.
Contacts before a conversation exists
The complete Messenger accepts directory and onOpenDirectoryContact. The host
supplies its authenticated address book; Robono does not invent contacts or
import permissions from another network. This works in ExpoMessenger,
WebMessenger, and mountRobonoMessenger.
Each directory entry has id, name, status, detail, and available.
Optional contactId, conversationId, and avatarUrl identify an existing chat
and its avatar. Entries already represented by a loaded conversation are hidden
to avoid duplicate rows. Search includes the directory. Unavailable entries show
the supplied explanation without opening a composer or making a send request.
For an available entry, onOpenDirectoryContact(entry, signal) must ask your
server to recheck membership/blocks and create or find the conversation. Return
its ConversationSummary. Repeated opens should return the same conversation.
Respect signal.aborted; late responses are discarded when the directory entry
is removed, permission changes, the popup closes, or the account is switched.
This is not a permission grant: Robono's regular server checks still apply.
On web, call messenger.updateDirectory(nextEntries) to update availability
without resetting the current chat. React hosts update the directory prop.
A directory does not copy historical messages or transfer acceptance of a
connection from another network. Keep those migration decisions on your server.
Friends, chat and menu appearance
Use Features & preview → Appearance to choose Name & logo, Friends screen, Friends menu, Chat screen, or Chat menu. The preview uses these shared SDK screens, including for Robono Messenger. Uploading a logo changes the draft; Save changes → Apply to live app publishes it (or Apply to test app for a test connection). Online inboxes refresh settings automatically and when reopened. No restart or reinstall is needed for configuration changes; apps must first install this SDK update.
The friends header reserves 145 × 38 logical pixels/points for either the logo or app name. Logos keep their proportions, fit inside this box, and align to its right edge. Text uses the same box and supports device/serif/monospace fonts, size, weight and color. The chat header identifies the contact/group; it does not repeat the app logo. Uploaded logos keep their own colors.
The MessagingAppearance.screens options customize friends-list colors, avatars,
last-message previews, branding text and direct/group header colors. menus.friends
and menus.chat set menu background, text/icon colors and optional entries. These
are display choices, never permission grants: entries still require the feature and
user authorization. Account access and permitted Block/Report actions stay available.
A host-provided appearance overrides server appearance; omit it to follow saved
website settings. A host-provided companyName overrides the configured app name.
Profile, media and chat options
The conversation menu provides Profile (Group details for groups), Shared media, and Chat options. Chat options contains notification muting, Privacy Lens when allowed, and confirmed deletion of the current user's chat history. Deleting a chat leaves the other person's copy intact; a new incoming message can return the chat to the inbox. The complete Messenger connects these actions to the authenticated inbox automatically.
When composing only a conversation screen with your own inbox, supply
conversationActions={{ muted, setMuted, deleteConversation }}. Both callbacks
return a promise and must enforce the signed-in user's permissions on your
server. Unavailable actions are hidden. Website customization controls the
menu entries through appearance.menus.chat.items.media and .options; it
does not grant access that the user's permissions deny.
Existing Bridge friends
Open an already accepted external-app user ↔ Robono-user connection in the standard Messenger using the original connection ID and retained history. See the Bridge Messenger guide and the included examples/existing-bridge-chat.tsx. This connector requires the matching core 0.13.0, server 0.32.0 and Expo 0.18.0 or web 0.17.0 release.
Multiple devices and delivered alerts
The supplied Messenger keeps its account inbox listener active while a conversation is open. Reads on another device refresh unread counts and reconcile delivered browser notifications. Only server-confirmed stale alerts are closed; newer messages remain. Closed browsers reconcile on the next open, because browser push requires user-visible notifications. See managed notification behavior.
Bubble appearance and delivery status
Choose Design → Chat screen → Messages & bubbles in the website customization tool. The shared preview uses the same renderer as the customer Messenger.
- Bubble corners: standard, square (90°), or more rounded.
- Bubble style: classic, a top tail on text/file bubbles (top right for sent messages, top left for received messages), or the original Messenger’s tighter sender-side bottom corner (3px, with 14px body corners). Voice messages keep their player shape; photos and videos fill their bubble without a padded outer background.
- Delivery status: a bar inside the bubble, flush with its right edge, or a circle with a checkmark. Bar mode offers sent, delivered and seen/heard/watched colors. Each outgoing item has its own indicator, including attachments sent together. Incoming messages have no delivery indicator.
A circle is empty while sending, gains a checkmark on delivery and fills with the accent color when consumed. Viewing status is only shown when receipt permissions allow it; styling never overrides those permissions.
These choices are stored in appearance.presentation.bubbleShape, appearance.presentation.bubbleStyle, and appearance.messageStatus (style, position, sent, delivered, consumed). Existing designs default to the inside edge bar and classic bubbles. Customers need a package version containing these controls before saved designs can render them.
The website's Calling settings control the optional message offer after an unanswered call. The shared panel presents one recording preview, Record again, Cancel and an explicit Send action. Drafts are not uploaded until Send.
The website’s Design → Chat screen → Writing area offers an optional Message field border and its color. The thin outline follows the field corners without changing its size. These are appearance.composer.fieldBorder and fieldBorderColor; existing designs remain borderless.
The 12px status circle can sit inside or below each outgoing bubble via
appearance.messageStatus.position: 'inside' | 'below' (default inside).
Message time independently uses appearance.messageTime.position: 'inside' |
'below' | 'slide' (default slide). Below-bubble metadata moves with its own
message during a swipe. These settings apply to web, iPhone and Android.
appearance.screens.chat.messageWidth limits long bubbles to 70, 88 or 94 percent
of the message area; short messages retain their natural width.
When top tails are selected, the delivery bar starts at the tail’s base with a rounded cap; it does not draw a stripe through the tail.
Parent message reviews
Use the shared BrowserMessageReviewInbox with the authenticated parent route described in the
server integration instructions.
Use the matching server and core packages, and confirm the public review API is available before enabling reviews.
import {MessageReviewClient} from '@robono/messaging';
import {BrowserMessageReviewInbox} from '@robono/messaging-web';
const reviewClient = new MessageReviewClient(async (operation, input) => {
const response = await fetch('/api/parent-message-reviews', {
method: 'POST', credentials: 'include',
headers: {'content-type': 'application/json'},
body: JSON.stringify({...input, operation}),
});
const result = await response.json();
if (!response.ok) throw Error(result.error?.message ?? 'Review unavailable');
return result;
});
// Use your authenticated transport/session and account directory on mobile.
<BrowserMessageReviewInbox client={reviewClient} name={userDisplayName}
conversationName={friendDisplayNameForConversation} />Keep the client stable while the signed-in account is unchanged, and replace it on
sign-out/account changes. Names are display data, never authorization. The parent
sees the child, intended friend, exact words and private photo/video/voice preview.
Pending and completed items are separate; only a pending item offers a decision.
Approved items with interrupted delivery offer Retry delivery. Media is cleared
when the item changes or the app backgrounds. Native hosts without Expo can use
MessagingReviewInbox with their own authorized renderMedia callback.
Directory contacts now open the conversation destination immediately, without an
“Opening chat” dialog. The shared screen keeps the friend's name and avatar visible
while onOpenDirectoryContact resolves. No messages or composer are mounted before
the authorized result. Return the conversation summary directly after the permission
check; refreshing contact lists or the inbox must not delay that result. Back,
account changes and revoked directory entries cancel pending opens and discard late
responses. Unavailable contacts explain their status in the same conversation pane.
This navigation correction is local and awaiting the combined SDK release.
Private Me chat
The shared friend list places the authenticated user's direct self conversation first and labels it Me. It uses the signed-in account's avatar. The conversation must come from the authorized inbox response (selfConversation); the UI never invents a conversation ID or substitutes another contact.
Account → Show Me in friends hides or restores that row without deleting messages. Complete Messenger integrations persist this preference on the current device/browser, partitioned by endpoint, namespace and user. With persistence disabled it lasts for the client session. Composable integrations can supply MessagingInboxClient({request, userId, preferences: {read, write}}) and pass the same inbox to MessagingAccountMenu / MessagingAccountScreen; custom preference adapters may sync the choice through the host's authenticated account settings. This is a personal account choice, not a network appearance default.
The complete Messenger uses the inbox’s saved appearance while a conversation loads. For a standalone conversation screen, initialAppearance supplies that same presentation fallback until the conversation settings arrive; appearance remains an explicit override. Neither option grants messaging or calling permissions.
Chat backup — unreleased
Website customization saves messaging.appearance.showChatBackup. false hides
Chat backup and closes an open backup page; true still requires the host's
account.backup client. Omission preserves existing host-controlled availability.
For server-retained history without personal backups, omit the backup client and
background workers. Existing personal archives are not deleted by this choice.
The shared backup screen follows Messenger account settings and supports backup status, account/storage actions, schedules, cellular policy, video inclusion, recovery keys and restore. Pass a MessagingBackupClient as account.backup. Core/native encryption and sample-data round trips are implemented; complete local-history storage, cloud-account integration and background jobs remain required before this is available to customers. See the backup implementation status.
