# Contexts

URL: https://notifly.io/docs/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](https://notifly.io/docs/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](https://notifly.io/docs/getting-started#environments).

## 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, &#x2A;*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`:

```bash
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:

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

In [step conditions](https://notifly.io/docs/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`):

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

See [In-app inbox](https://notifly.io/docs/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](https://notifly.io/docs/api). Each operation has a page in the [API reference](https://notifly.io/docs/api-reference), and they are in the [OpenAPI document](https://notifly.io/docs/api/openapi.json) under the `Contexts` tag.

| Operation                                                                    | Request                                                                                                |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| [Create a context](https://notifly.io/docs/api-reference/contexts/ContextsController_createContext) | `POST /v2/contexts` with `type`, `id` and optional `data`. A duplicate returns `409`.                  |
| [List contexts](https://notifly.io/docs/api-reference/contexts/ContextsController_listContexts)     | `GET /v2/contexts`, filtered by `type`, `id` or `search`, paginated with `limit`, `after` and `before` |
| [Retrieve a context](https://notifly.io/docs/api-reference/contexts/ContextsController_getContext)  | `GET /v2/contexts/{type}/{id}`                                                                         |
| [Update a context](https://notifly.io/docs/api-reference/contexts/ContextsController_updateContext) | `PATCH /v2/contexts/{type}/{id}` with `data`. Only `data` changes.                                     |
| [Delete a context](https://notifly.io/docs/api-reference/contexts/ContextsController_deleteContext) | `DELETE /v2/contexts/{type}/{id}`                                                                      |

```bash
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" } }'
```
