Set up Inbox

The Inbox component displays a notification bell that opens the subscriber’s notifications and preferences. Start with your application’s existing WorldVisa connection, then add the component where you want people to find their updates.

Installation

Use @wv/react, the private React package maintained in this workspace. It is not a public npm package. Add it through your application’s existing workspace dependency setup.

Next.js
React

Import Inbox inside a client component. The same React package works with the Next.js App Router.

'use client';

import { Inbox, type InboxProps } from '@wv/react';

export function NotificationInbox(props: InboxProps) {
  return <Inbox {...props} />;
}

Import Inbox into the component that renders your header, sidebar, or notification area.

import { Inbox, type InboxProps } from '@wv/react';

export function NotificationInbox(props: InboxProps) {
  return <Inbox {...props} />;
}

@wv/react supports React 18 and React 19. Use the same version of react-dom as React when rendering the Inbox UI.

Use Inbox with real subscribers

Connect Inbox to the environment where your workflows run. The application identifier identifies that environment; the subscriber ID identifies the person whose notifications should be displayed. You also need the API and WebSocket origins from your application’s configuration. Set both explicitly so the component connects to WorldVisa services.

Next.js
React

'use client';

import { Inbox } from '@wv/react';

type NotificationInboxProps = {
  applicationIdentifier: string;
  subscriberId: string;
  subscriberHash: string;
  backendUrl: string;
  socketUrl: string;
};

export function NotificationInbox(props: NotificationInboxProps) {
  return (
    <Inbox
      applicationIdentifier={props.applicationIdentifier}
      subscriber={props.subscriberId}
      subscriberHash={props.subscriberHash}
      backendUrl={props.backendUrl}
      socketUrl={props.socketUrl}
    />
  );
}

import { Inbox } from '@wv/react';

type NotificationInboxProps = {
  applicationIdentifier: string;
  subscriberId: string;
  subscriberHash: string;
  backendUrl: string;
  socketUrl: string;
};

export function NotificationInbox(props: NotificationInboxProps) {
  return (
    <Inbox
      applicationIdentifier={props.applicationIdentifier}
      subscriber={props.subscriberId}
      subscriberHash={props.subscriberHash}
      backendUrl={props.backendUrl}
      socketUrl={props.socketUrl}
    />
  );
}

The props come from your application’s configuration and authenticated session. These examples use subscriber HMAC authentication. If your application uses token authentication, follow its existing getToken integration instead.

Secure the subscriber session

Fetch the subscriber ID and its credentials from your authenticated backend. The backend must verify who is signed in before issuing an Inbox hash or token. Never pass a secret API key to Inbox or calculate a hash in browser code. For HMAC authentication, pass subscriberHash. When you also provide context, pass the corresponding contextHash. Hash the exact context object sent to Inbox, including nested data. See Inbox with context for the server-side example.

A public application identifier does not authorize access to someone else’s notifications. Keep the subscriber identity and credentials tied to the signed-in session.

Add portal or workspace context

If your workflows send notifications with context, initialize Inbox with the same context type and ID. For example, CRM uses portal context to keep its feed scoped to CRM notifications.

import { Inbox, type InboxProps } from '@wv/react';

export function CrmInbox(props: InboxProps) {
  return <Inbox {...props} context={{ portal: 'crm' }} />;
}

Supply the credentials for that context as part of props. When users switch workspaces, refresh their authorized context and credentials together. See Multi-tenancy.

Pass subscriber profile fields

Use a subscriber object when your integration needs to supply profile fields at session initialization.

import { Inbox, type InboxProps } from '@wv/react';

export function SubscriberInbox(props: InboxProps) {
  return (
    <Inbox
      {...props}
      subscriber={{
        subscriberId: 'staff-123',
        firstName: 'Alex',
        email: 'alex@example.com',
        locale: 'en-US',
      }}
    />
  );
}

Use the real subscriber ID from your authenticated session. New subscribers can be created during session initialization. Updating an existing subscriber’s profile requires the configured authentication checks, including subscriberHash when HMAC is enabled.

Send your first notification

Check the environment

Use the same environment for the workflow, subscriber, application identifier, API origin, and WebSocket origin.

Create an in-app message

Add an in-app step to a workflow and write a subject and body. Create a workflow walks through this process.

Trigger it for your subscriber

Send the workflow event from your backend with the subscriber ID and matching context. Keep the trigger’s transaction ID if you need to investigate the delivery.

Open Inbox

Check the bell’s unread count and open the notification list. If no message appears, inspect the Activity Feed, then check the subscriber, context, and browser connections.

The examples on the following pages focus on one customization at a time. Keep the working connection and authentication settings from this guide when you use them in your application.

Getting Started

Integrate <Inbox />

Build a Workflow

Integrate Channels Providers

Account

Installation

Use Inbox with real subscribers

Secure the subscriber session

Add portal or workspace context

Pass subscriber profile fields

Send your first notification

​Installation

​Use Inbox with real subscribers

​Secure the subscriber session

​Add portal or workspace context

​Pass subscriber profile fields

​Send your first notification

Installation

Use Inbox with real subscribers

Secure the subscriber session

Add portal or workspace context

Pass subscriber profile fields

Send your first notification