How do contexts work in Novu?

context: {
  // Simple string: type and id only
  tenant: "acme-corp",

  // Object with id
  app: { id: "billing" },

  // Object with id and metadata
  region: {
    id: "us-east",
    data: {
      name: "US East",
      timezone: "America/New_York",
    },
  },
}

Welcome to {{context.tenant.data.name}}! Your {{context.tenant.data.plan}} plan is active.

  </Tab>
  <Tab title="Python">
```python
import os
import novu_py
from novu_py import Novu

with Novu(secret_key=os.getenv("NOVU_SECRET_KEY", "")) as novu:
    novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
        workflow_id="invoice-paid",
        to={"subscriber_id": "user-123"},
        payload={"amount": "$250"},
        context={
            "tenant": {
                "id": "acme-corp",
                "data": {
                    "name": "Acme Corporation",
                    "plan": "enterprise",
                },
            },
        },
    ))

novugo "github.com/novuhq/novu-go"
"github.com/novuhq/novu-go/models/components"

  </Tab>
  <Tab title="PHP">
```php
use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$sdk->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'invoice-paid',
        to: new Components\SubscriberPayloadDto(subscriberId: 'user-123'),
        payload: ['amount' => '$250'],
        context: [
            'tenant' => [
                'id' => 'acme-corp',
                'data' => [
                    'name' => 'Acme Corporation',
                    'plan' => 'enterprise',
                ],
            ],
        ],
    ),
);

  </Tab>
  <Tab title="Java">
```java
import co.novu.Novu;
import co.novu.models.components.*;
import java.util.Map;

Novu novu = Novu.builder()
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger()
    .body(TriggerEventRequestDto.builder()
        .workflowId("invoice-paid")
        .to(To2.of(SubscriberPayloadDto.builder()
            .subscriberId("user-123")
            .build()))
        .payload(Map.of("amount", "$250"))
        .context(Map.ofEntries(
            Map.entry("tenant", TriggerEventRequestDtoContextUnion.of(
                TriggerEventRequestDtoContext2.builder()
                    .id("acme-corp")
                    .data(Map.ofEntries(
                        Map.entry("name", "Acme Corporation"),
                        Map.entry("plan", "enterprise")))
                    .build()))))
        .build())
    .call();

**Inline on workflow trigger (server-side):** When you trigger a workflow with a rich context object that includes `data`, Novu creates the context if it is missing or replaces stored `data` if it already exists. This works like subscriber upsert and is useful when your backend already has the latest tenant metadata at trigger time. Pass only the context `id` as a string when you want to reference existing data without changing it.

**Ahead of time via API or dashboard:** Create contexts with initial `data` before you need them, then [update context data](/api-reference/contexts/update-a-context) when metadata changes (for example, tenant name or plan). Use this when you want a single source of truth outside of triggers.

**Inbox:** Session initialization can auto-create missing contexts but never updates existing context `data`. Do not rely on the Inbox to refresh tenant metadata.

Recommended approach for multi-tenant apps:

1. [Create the context](/api-reference/contexts/create-a-context) with initial `data` before you need it, or pass `data` on your first server-side trigger.
2. Keep metadata current through [workflow triggers with inline `data`](/platform/workflow/trigger-workflow#trigger-a-workflow-with-context), the Contexts API, or the dashboard.
3. Pass only context keys and `id` values to the Inbox unless you are creating a context for the first time.

Pass the same context to both your workflow trigger and the Inbox `context` prop. See [Inbox with context](/platform/inbox/configuration/inbox-with-context) for the matching rules and troubleshooting steps.