# Set up notification events in the console

Turn email and push on for your organization, choose each system event's channels, create your own events with their email, and see what was delivered.

A notification event is one kind of message your users get, such as an
invitation or "a report is ready". Each event says whether it goes by email,
push or both, and the [inbox](/notifications/inbox) keeps every one of them.
This guide sets them up in the console: the switches for the whole
organization, the events BuildBase sends for you, and an event of your own
that Acme Analytics sends when a report is ready.

> **Note:**
  A console role that can read and change notification events. For email, a
  sender marked **System default** ([connect a
  sender](/email/connect-a-sender)); for push, browsers subscribed from your app
  ([set up web push](/push-notifications/setup)).

## 1. Open Notification events

[Open Notification events in the console](https://console.buildbase.app/dashboard/admin/notifications)

In the left rail choose **Messaging**, then **Notification events** under
**Configuration**. The page, **Notifications**, has four tabs: **Custom**,
**System**, **Global** and **Delivery log**.

![Notification events under Messaging: the Notification events menu item highlighted as step 1, the Custom, System, Global and Delivery log tabs outlined, and Custom notifications open](/images/notifications/events/tabs.webp)

## 2. Choose the channels for the whole organization

On **Global**, the **Global notification settings** card has **Email
notifications** and **Push notifications**. Each saves the moment you switch
it. Off, no event sends by that channel, whatever the event says, and push
campaigns are refused too. This is the first of [the four
gates](/notifications/overview#the-four-gates) every notification passes.

![Global notification settings: the Email notifications switch highlighted as step 2, and Push notifications below it](/images/notifications/events/global.webp)

## System events

The events BuildBase sends for you, such as invitations, billing and credit
notices, are on **System**, one card per category. Each event has an email
switch and a push switch, and both save at once.

### 3. Choose each system event's channels

Turn a channel off for one event with its switch. **Edit** on a row opens
**Configure system event**, which changes the same two channels: a system
event's name, description and email template are fixed, and it cannot be
deleted.

![The Account & security category of System notifications: the Welcome event's email and push switches, with its push switch highlighted as step 3](/images/notifications/events/system.webp)

## Custom events

Your own events, the ones your server sends with
[`bb.notification.send()`](/notifications/overview), are on **Custom**.

### 4. Create an event

Press **Create custom event**. In **Create notification event**, fill
**Name**, **Slug** (what your code sends, such as `report_ready`),
**Description** and **Category**. Turn on **User can toggle this in workspace
settings** if each member may turn it off for themselves. Press **Create**.

![Create notification event: Name Report ready, the Slug report_ready highlighted as step 4, the description, Category reports and the user toggle](/images/notifications/events/create.webp)

The event is made with email and push on, and with its own email template,
`custom-notification-<slug>`. Your plan caps how many custom events you have;
the meter beside **Create custom event** counts them.

### 5. Change it later

**Edit** on its row opens **Edit notification event**: **Enabled** switches
the whole event off, **Email** and **Push** choose its channels, and **User
control** is the same per-member toggle. Press **Save changes**.

![Edit notification event, with User control highlighted as step 5, and the Enabled, Email and Push switches](/images/notifications/events/edit.webp)

### 6. Write its email

In the left rail choose **Templates** under **Email**. The event's template
is listed under its name, **Report ready**, in the **Notification** category
(filter **Category** to find it in a long list); its id is
`custom-notification-report_ready`. Open it with the edit button. Its body
starts as the event's name and `{{message}}`, the text your server sends;
write the email around it ([create a template](/email/create-a-template)).

![Email templates: the Report ready row, category Notification, highlighted as step 6, with its edit button among the actions](/images/notifications/events/template.webp)

### 7. Send it from your server

```typescript
await bb.notification.send(workspaceId, 'report_ready', userId, {
  title: 'Your cohort report is ready',
  message: 'The March cohort report has finished.',
  url: '/reports/march',
});
```

Leave out `userId` to send it to every member of the workspace. The
[notifications overview](/notifications/overview) has every field and what
comes back.

## 8. See what was delivered

**Delivery log** has one row per person per notification: the event, who got
it, in which workspace, what **Email** and **Push** each did, and whether they
**Read** it. The totals above it are for the last 30 days.

![Delivery log: the totals for the last 30 days, and the row Your cohort report is ready, to Priya Shah in Northwind Traders, highlighted as step 8, with email Sent and push Skipped](/images/notifications/events/delivery-log.webp)

Each row also says where the send came from, under its slug: here **Console
test**, since the guide's example was sent from the console. **Skipped** with
"Push is not set up for this organization" means the organization has no
VAPID keys yet, so nothing could be pushed ([set up web
push](/push-notifications/setup)).

## 9. One person's notifications

The same rows for one person are on their page: **Users**, then the user, tab
**Notifications**. It is what they see in their [inbox](/notifications/inbox).

![Priya Shah's Notifications tab: her totals, and the row Your cohort report is ready highlighted as step 9, unread](/images/notifications/events/user-deliveries.webp)

## Check it works

Send the event once from your server. A row appears on **Delivery log** with
the channels it used, and the item is in that person's inbox.

## Things to watch out for

- **A slug your server sends before you create it registers itself.** It
  becomes a custom event with push on and no email template, and it counts
  toward your plan's custom events like one made here ([events you have not
  set up](/notifications/overview#events-you-have-not-set-up)). The console
  cannot attach a template to it: set `emailTemplate` over the API.
- **A slug is stored lowercase**, and any character other than a letter, a
  digit, `.`, `_`, `:` or `-` becomes `-`.
- **Deleting a custom event deletes its email template too,** the
  `custom-notification-<slug>` one it was made with. A template you attached
  over the API stays, since it may serve something else. System events cannot
  be deleted.
- **A member's own choice applies only to an event with user control.** An
  event without it ignores members' preferences, which suits security and
  billing notices.

## If something goes wrong

| What you see                                            | What it means                                                                                                |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `NOTIFICATION_EVENT_NOT_SET_UP` (403) on a send         | A new slug, with your plan's custom events used up. Create it here once there is room, or send one you have. |
| `429` on a send                                         | More than 300 sends in an hour from one workspace. Try again later.                                          |
| Failed to create email template for notification event. | The event was not made because its template could not be. Try **Create** again.                              |
| A send answers `sent: true` with both channels `false`  | A gate blocked both: the switches on **Global**, the event's own channels, or the person's preferences.      |
| `reason: 'event_disabled'`                              | **Enabled** is off on the event.                                                                             |

## Next Steps

- [Notifications overview](/notifications/overview) - the send call, what comes back and the four gates.
- [Inbox](/notifications/inbox) - the bell and the list your users see.
- [Set up web push](/push-notifications/setup) - subscribe browsers so push has somewhere to go.
- [Slack alerts](/notifications/slack) - the same system events, to your team's channel.