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

# Notification types & categories

> Define the reusable catalog of notifications your app can send — event keys, default channels, templates, and opt-out rules — and organize them into categories.

A **notification type** is the reusable definition of one kind of notification your application can send — for example `build_failed`, `invoice_payment`, or `chat_direct_mentions`. Your app never hard-codes message text; instead it refers to a type by its **event key**, and the type decides the default channels, the title and message templates, and whether users are allowed to turn it off.

**Categories** simply group related types together (e.g., *Billing*, *Collaboration*, *Security*) so they are easier to present in a preferences screen.

<Note>
  Types and categories are scoped per environment. Configure them independently for `development`, `staging`, and `production`.
</Note>

## Ready-made types

Every project starts with a catalog of common notification types already created for you (such as `password_reset`, `application_deployed`, `billing_payment_reminders`, and many more). You can use them as-is, edit them, or add your own. Re-activating the module never overwrites your edits.

## Anatomy of a notification type

| Field                                              | Meaning                                                                                                                                          |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Event key** (`eventKey`)                         | The stable identifier your app passes to `emitNotification`. Unique per environment. Use `lower_snake_case` (e.g., `order_shipped`).             |
| **Name**                                           | A human-readable label shown in the UI.                                                                                                          |
| **Description**                                    | Optional explanation of when this notification fires.                                                                                            |
| **Category**                                       | The category this type belongs to.                                                                                                               |
| **Default channels** (`defaultChannels`)           | The channels used when a recipient has no specific preference (e.g., `["in_app", "email"]`).                                                     |
| **Title template** (`titleTemplate`)               | Template for the notification title. Supports variables from `params` (e.g., `Build {{.buildId}} failed`). If left empty, the event key is used. |
| **Message template** (`messageTemplate`)           | Template for the body. If left empty, the title is reused.                                                                                       |
| **Mandatory** (`isMandatory`)                      | If `true`, every user receives it — preferences cannot switch it off (use for security or legal notices).                                        |
| **Can be disabled** (`canBeDisabled`)              | If `false`, users cannot opt out (similar effect to mandatory).                                                                                  |
| **Default subscribed** (`defaultSubscribed`)       | Whether users are opted in by default when they have no preference row yet.                                                                      |
| **Default expiry (hours)** (`defaultExpiresHours`) | How long an in-app item stays before it expires, unless overridden when sending.                                                                 |
| **Channel templates** (`channelTemplates`)         | Per-channel delivery settings — for example the email provider template id and its required variables.                                           |
| **Active** (`isActive`)                            | Turn the whole type on or off. Sending an inactive type is rejected.                                                                             |

## Configure from the Archie web app

<Steps>
  <Step title="Open the Types tab">
    Navigate to **App Services → Notifications** and open the **Types** tab.
  </Step>

  <Step title="Create a category (optional)">
    Open **Categories** first and click **+ Add Category** to create a group such as *Billing*. Give it a **key** and a **name**.
  </Step>

  <Step title="Add a type">
    Back in **Types**, click **+ Add Type** and fill in:

    * **Event Key** — e.g., `order_shipped`.
    * **Name** and **Description**.
    * **Category** — pick the group it belongs to.
    * **Default Channels** — e.g., *In-app* and *Email*.
    * **Title / Message templates** — optionally with `{{.variable}}` placeholders.
    * Toggles for **Mandatory**, **Can be disabled**, **Default subscribed**, and **Active**.
  </Step>

  <Step title="Save">
    Click **Save**.
  </Step>
</Steps>

You can edit or deactivate a type at any time; changes take effect immediately for the next notification sent.

## Configure through the GraphQL API

Notification types and categories are regular tables in your project, so they are available through the standard auto-generated [GraphQL](/docs/features/backend/graphql-api-explorer/overview) operations on your project endpoint.

**Endpoint**

```
https://archie-core.services.archie.com/graphql
```

**Required headers**

| Header          | Value                                                            |
| --------------- | ---------------------------------------------------------------- |
| `X-Project-Id`  | Your project id                                                  |
| `X-Environment` | The target environment (e.g., `master`, `staging`, `production`) |
| `Authorization` | `Bearer <accessToken>`                                           |

### Create a category

```graphql theme={null}
mutation CreateCategory {
  createArchieNotificationCategories(
    input: {
      key: "billing"
      name: "Billing"
      description: "Invoices, payments and credit alerts"
      sortOrder: 10
      isActive: true
    }
  ) {
    id
    key
    name
  }
}
```

### Create a notification type

```graphql theme={null}
mutation CreateType {
  createArchieNotificationTypes(
    input: {
      eventKey: "order_shipped"
      name: "Order Shipped"
      description: "Sent when a customer's order leaves the warehouse"
      defaultChannels: ["in_app", "email"]
      titleTemplate: "Your order {{.orderId}} is on its way"
      messageTemplate: "Order {{.orderId}} shipped and should arrive on {{.eta}}."
      isMandatory: false
      canBeDisabled: true
      defaultSubscribed: true
      defaultExpiresHours: 720
      isActive: true
    }
  ) {
    id
    eventKey
    name
    isActive
  }
}
```

<Tip>
  Any variable you reference in a template (e.g., `{{.orderId}}`) must be supplied in the `params` object when you send the notification — see [Sending notifications](/docs/features/backend/app-services/notifications/sending-notifications).
</Tip>

### List the catalog

```graphql theme={null}
query ListTypes {
  archieNotificationTypes(
    filter: { isActive: { equals: true } }
    orderBy: { sortOrder: ASC }
  ) {
    items {
      id
      eventKey
      name
      defaultChannels
      isMandatory
      defaultSubscribed
    }
  }
}
```

<Note>
  **Soft-deleted records.** List queries exclude soft-deleted rows by default. To include records that have been soft-deleted, pass the `withDeleted: true` argument on the list query (e.g., `archieNotificationTypes(withDeleted: true) { items { id eventKey } }`). Omit it — or set it to `false` — to return only active rows.
</Note>

### Update or deactivate a type

```graphql theme={null}
mutation DeactivateType {
  updateArchieNotificationTypes(
    id: "b2c8…"
    input: { isActive: false }
  ) {
    id
    eventKey
    isActive
  }
}
```

<Note>
  In the API, fields are shown in `camelCase` (e.g., `eventKey`, `defaultChannels`, `isActive`). The API Explorer's autocomplete and documentation panel always show the exact names and arguments available for your project.
</Note>

## Next step

Once your catalog exists, let users choose what they receive in [User preferences](/docs/features/backend/app-services/notifications/user-preferences), or jump straight to [Sending notifications](/docs/features/backend/app-services/notifications/sending-notifications).