Contexts

Tag a trigger with the tenant, workspace or app it belongs to. Pass context on a trigger, read it in templates and conditions, and scope inbox feeds by it.

A context describes where a notification comes from: the tenant, workspace, organization or app inside your product that it belongs to. Create a context once, attach it to triggers, and use it to personalize content, branch with step conditions and keep one tenant's inbox feed apart from another's.

If your product serves one audience, you do not need contexts. They are for multi-tenant products, where the same subscriber can belong to several workspaces.

The context object

Field	Notes
`type`	The kind of context, such as `tenant`, `workspace` or `app`. 1 to 100 characters.
`id`	Your identifier for this context, such as `acme-org`. 1 to 100 characters.
`data`	An optional JSON object of your own attributes, such as `{ "name": "Acme Corp", "plan": "enterprise" }`. Up to 64 KB.

type and id may contain only letters, digits, _ and -. A context is unique by its type and id within an environment, and is addressed as type:id (for example tenant:acme-org). Contexts belong to one environment.

Create a context

Open Contexts in the Data group of the sidebar and choose Create context. Fill in the Identifier, the Context type and, optionally, Custom data (JSON). The page lists contexts by type and ID.

You do not have to create a context before using it. A trigger that names one creates it if it is missing (see the next section).

Pass a context on a trigger

Add a context object to the trigger request. Each key is a context type, and each value is either the context ID as a string or an object with an id and optional data:

curl -X POST https://api.notifly.io/v1/events/trigger \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<workflow-id>",
    "to": { "subscriberId": "<subscriber-id>" },
    "payload": { "body": "Your report is ready" },
    "context": {
      "tenant": { "id": "acme-org", "data": { "name": "Acme Corp" } },
      "app": "reports"
    }
  }'

A context that does not exist yet is created. If you send data for one that does, its stored data is replaced when the new data differs.
A trigger can carry up to 5 context types. More than that, a malformed context, or a context whose data is over 64 KB, is rejected with a 422 validation error.
The same shape is accepted when previewing a workflow in the dashboard, so you can try a context before sending.

Use a context in a workflow

Inside the workflow, the context is available as context.<type>, with id and data properties:

Hello from {{context.tenant.data.name}} ({{context.tenant.id}})

In step conditions, pick context.<type>.id or context.<type>.data.<field> to run a step only for some tenants.

Scope the inbox to a context

The Inbox accepts a context option so a feed shows only the notifications triggered with that context. Pass it on the Inbox component. When HMAC is enabled for your in-app integration, the context must be signed too: compute contextHash on your server with your secret key and pass it alongside, or the session is refused with Please provide a valid context HMAC hash. The hash is an HMAC-SHA256, keyed with your secret key, over the canonicalised JSON of the context, so key order does not change it. The @notiflyio/react README shows the exact helper (it canonicalises with @tufjs/canonical-json):

<Inbox
  applicationIdentifier="<app-identifier>"
  subscriber="<subscriber-id>"
  context={{ tenant: 'acme-org' }}
  contextHash="<hmac>"
/>

See In-app inbox for the rest of the component.

REST API

Contexts are managed under /v2/contexts, authenticated with an ApiKey like the rest of the REST API. Each operation has a page in the API reference, and they are in the OpenAPI document under the Contexts tag.

Operation	Request
Create a context	`POST /v2/contexts` with `type`, `id` and optional `data`. A duplicate returns `409`.
List contexts	`GET /v2/contexts`, filtered by `type`, `id` or `search`, paginated with `limit`, `after` and `before`
Retrieve a context	`GET /v2/contexts/{type}/{id}`
Update a context	`PATCH /v2/contexts/{type}/{id}` with `data`. Only `data` changes.
Delete a context	`DELETE /v2/contexts/{type}/{id}`

curl -X POST https://api.notifly.io/v2/contexts \
  -H "Authorization: ApiKey $NOTIFLY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "tenant", "id": "acme-org", "data": { "name": "Acme Corp" } }'