Notification types & 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.

Types and categories are scoped per environment. Configure them independently for development, staging, and production.

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

Open the Types tab

Navigate to App Services → Notifications and open the Types tab.

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.

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.

Save

Click Save.

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 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

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

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
  }
}

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.

List the catalog

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

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.

Update or deactivate a type

mutation DeactivateType {
  updateArchieNotificationTypes(
    id: "b2c8…"
    input: { isActive: false }
  ) {
    id
    eventKey
    isActive
  }
}

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.

Next step

Once your catalog exists, let users choose what they receive in User preferences, or jump straight to Sending notifications.

Home

Blueprint

Design

Frontend

Backend

Assets

Ready-made types

Anatomy of a notification type

Configure from the Archie web app

Configure through the GraphQL API

Create a category

Create a notification type

List the catalog

Update or deactivate a type

Next step

​Ready-made types

​Anatomy of a notification type

​Configure from the Archie web app

​Configure through the GraphQL API

​Create a category

​Create a notification type

​List the catalog

​Update or deactivate a type

​Next step

Ready-made types

Anatomy of a notification type

Configure from the Archie web app

Configure through the GraphQL API

Create a category

Create a notification type

List the catalog

Update or deactivate a type

Next step