> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldvisagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Inbox

> Connect the WorldVisa Inbox to your application, authenticate the signed-in subscriber, and display real-time notifications in React or Next.js.

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.

> [tab] Next.js
>
> Import Inbox inside a client component. The same React package works with the Next.js App Router.
>
> ```tsx theme={null}
> 'use client';
>
> import { Inbox, type InboxProps } from '@wv/react';
>
> export function NotificationInbox(props: InboxProps) {
>   return <Inbox {...props} />;
> }
> ```

> [tab] React
>
> Import Inbox into the component that renders your header, sidebar, or notification area.
>
> ```tsx theme={null}
> import { Inbox, type InboxProps } from '@wv/react';
>
> export function NotificationInbox(props: InboxProps) {
>   return <Inbox {...props} />;
> }
> ```

> [!NOTE]
>
> `@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.

> [tab] Next.js
>
> ```tsx theme={null}
> '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}
>     />
>   );
> }
> ```

> [tab] React
>
> ```tsx theme={null}
> 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](https://docs.worldvisagroup.com/developers/inbox/configuration/inbox-with-context.md#how-to-secure-your-context) for the server-side example.

> [!WARNING]
>
> 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.

```tsx theme={null}
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](https://docs.worldvisagroup.com/developers/inbox/advanced-features/multi-tenancy.md).

## Pass subscriber profile fields

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

```tsx theme={null}
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

**1. Check the environment**

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

**2. Create an in-app message**

Add an in-app step to a workflow and write a subject and body. [Create a workflow](https://docs.worldvisagroup.com/developers/workflow/create-a-workflow.md) walks through this process.

**3. 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.

**4. Open Inbox**

Check the bell’s unread count and open the notification list. If no message appears, inspect the [Activity Feed](https://docs.worldvisagroup.com/developers/workflow/monitor-and-debug-workflow.md), 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.


## Related topics

- [WorldVisa Inbox](https://docs.worldvisagroup.com/developers/inbox.md)
- [Inbox with Context](https://docs.worldvisagroup.com/developers/inbox/configuration/inbox-with-context.md)
- [Schedule](https://docs.worldvisagroup.com/developers/inbox/features/schedule.md)
- [Notification Click Behavior](https://docs.worldvisagroup.com/developers/inbox/advanced-customization/notification-click-behavior.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.