Multi-tenancy

Multi-tenancy in WorldVisa lets you isolate notifications for different organizations or workspaces within the same WorldVisa environment. Instead of creating separate subscribers or workflows for each tenant, you can use contexts to define and manage tenant boundaries.

This guide assumes you already understand what contexts are. If not, start with Contexts.

Use your application’s existing connection and authentication settings with these examples. Set up Inbox covers the application identifier, subscriber, API and WebSocket URLs, and subscriber credentials.

How multi-tenancy works

Multi-tenancy in WorldVisa is built on top of Contexts, which act as lightweight tags that group notifications by logical boundaries such as tenants or workspaces. When a notification is triggered with a tenant context, WorldVisa automatically associates all notifications and preferences with that tenant. The same tenant context passed to the <Inbox /> filters notifications for that specific organization, ensuring users only see messages relevant to their workspace.

How to implement multi-tenancy

Implementing a multi-tenant system involves a few key steps:

Define a tenant context

A Tenant Context is a JSON object that identifies a specific tenant and can store any related data you need, such as company name, logo, or plan type. You can create a tenant context using the WorldVisa dashboard, API or from the <Inbox />. if it doesn’t already exist, WorldVisa automatically creates it. Here are ways you can pass context:

// Simple tenant ID

context: {
  tenant: 'workspace-123' 
}

// Rich tenant object

context: {
  tenant: {
    id: 'workspace-123',
    data: {
      name: 'WorldVisa workspace',
      logo: 'https://cdn.acme.com/logo.png'
    }
  }
}

You can also manage all tenant contexts centrally from the WorldVisa dashboard or API.

To learn more about creating, updating, and deleting contexts, see Manage contexts.

Applying tenant context in workflows

Once you’ve defined your tenant context, you can use it when triggering workflows. During a workflow trigger, WorldVisa first checks if that context already exists. If not, WorldVisa automatically creates it. If it exists and you pass a data object inline, WorldVisa updates the stored tenant metadata - similar to subscriber upsert. If you pass only the tenant identifier as a string, WorldVisa reuses the existing record without modifying data. Inbox initialization always finds or creates contexts but never updates existing data. Send this JSON body from your authenticated backend to POST /v1/events/trigger. Use the API origin and credentials for the same environment as Inbox.

{
  "name": "workspace-update",
  "to": { "subscriberId": "staff-123" },
  "payload": { "recordId": "record-456" },
  "context": {
    "tenant": {
      "id": "workspace-123",
      "data": { "name": "WorldVisa workspace" }
    }
  }
}

In this example:

The tenant context identifies the workspace.
Notifications triggered with this tenant context will be isolated to that tenant’s workspace.
The same tenant ID must be passed to the Inbox to display these notifications.

Learn more about applying Context in workflows in Contexts in Workflows documentation.

Filter the Inbox by tenant

Once your workflows are sending tenant-scoped notifications, you can filter the <Inbox /> so that each subscriber only sees notifications relevant to their tenant. This is done by passing the same tenant context used in your workflow triggers to the <Inbox />.

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

<Inbox
  applicationIdentifier="APPLICATION_IDENTIFIER"
  subscriber="SUBSCRIBER_ID"
  context={{
    tenant: {
      id: 'workspace-123',
      data: {
        name: 'WorldVisa workspace',
        plan: 'enterprise',
      },
    },
  }}
/>

In this setup:

The <Inbox /> filters notifications based on an exact context match.
Only notifications triggered with tenant: { id: 'workspace-123' } will appear in the <Inbox />.
Notifications from other tenants are automatically excluded.

If the tenant context doesn’t already exist in WorldVisa, the Inbox will automatically find or create it. Learn more in Inbox with Context.

Customize notification content based on tenant

With contexts, you can use tenant-level data to dynamically personalize notification content, branding, and workflow logic, all from a single workflow definition. This eliminates the need to duplicate workflows or templates for each tenant while still keeping the experience distinct and relevant.

Using tenant data in templates

Once a tenant context is created, its data becomes accessible in all template editors (email, in-app, SMS, and push) through the {{context}} helper.

Dynamic logic per tenant

You can also use tenant context data to control conditional logic inside your workflows. For example, you may want to send certain updates only to enterprise tenants.

To learn more about customizing notification content with context, refer to the Contexts in Workflows documentation.

Verify workspace isolation

Authorize the workspace on your backend before issuing Inbox credentials. Do not trust a tenant ID supplied by the browser. When a user switches workspaces, refresh the context and its token or hash, then reconnect Inbox with that authorized context. Test with one subscriber in two workspaces. Trigger a message in each workspace and confirm that switching context shows only the matching feed. Development and production are separate environments; a tenant context does not replace that separation.

Getting Started

Integrate <Inbox />

Build a Workflow

Integrate Channels Providers

Account

How multi-tenancy works

How to implement multi-tenancy

Define a tenant context

Applying tenant context in workflows

Filter the Inbox by tenant

Customize notification content based on tenant

Using tenant data in templates

Dynamic logic per tenant

Verify workspace isolation

​How multi-tenancy works

​How to implement multi-tenancy

​Define a tenant context

​Applying tenant context in workflows

​Filter the Inbox by tenant

​Customize notification content based on tenant

​Using tenant data in templates

​Dynamic logic per tenant

​Verify workspace isolation

How multi-tenancy works

How to implement multi-tenancy

Define a tenant context

Applying tenant context in workflows

Filter the Inbox by tenant

Customize notification content based on tenant

Using tenant data in templates

Dynamic logic per tenant

Verify workspace isolation