> For the complete documentation index, see [llms.txt](https://bl-scripts-1.gitbook.io/bl-scripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bl-scripts-1.gitbook.io/bl-scripts-docs/bl-notify.md).

# BL NOTIFY

### Overview

**BL NOTIFY** is a premium FiveM notification system for advanced, customizable in game alerts.

The resource replaces native framework notifications with a modern HTML based UI and supports  **QBCore**, **Qbox**, and **ESX** with full auto detection. It includes optional server side logging and version checking, and a built in admin test menu.

#### Features

* Modern HTML/CSS notification UI with smooth animations
* Notification types: `success`, `error`, `info`, `warning`, `neutral`
* Configurable screen position (e.g. `top right`, `bottom left`)
* framework support (QBCore, Qbox, ESX)
* framework notification replacement:
  * `lib.notify` (Qbox / ox\_lib)
  * `QBCore:Notify` (QBCore)
  * `ESX.ShowNotification` (ESX)
* Client and server exports
* Optional Discord, Fivemerr, and Fivemanage logging
* Version checking on startup
* Admin test menu via `/notifytest`
* Full UI customization (HTML, CSS, JS)

### Requirements

#### Required

* FXServer
* Asset Pack

```lua
dependency '/assetpacks'
```

#### Framework (one of)

* **Qbox:** `ox_lib` + `qbx_core`
* **QBCore:** `qb-core`
* **ESX:** `es_extended`

{% hint style="info" %}
For Qbox, `Config.ReplaceOXNotify = true` is required
{% endhint %}

#### Optional

* `fmsdk` (Fivemanage SDK logging)

### Installation

#### Quick Start

**1. Add the Resource**

Add `bl_notify` to your server resources folder.

**2. Configure**

Edit:

```
config/config.lua
```

Set your framework (or leave `"auto"`), notification position, and replace toggles.

**3. Add to server.cfg**

**Qbox example:**

```cfg
ensure ox_lib
ensure qbx_core
ensure bl_notify
```

**QBCore example:**

```cfg
ensure qb-core
ensure bl_notify
```

**ESX example:**

```cfg
ensure es_extended
ensure bl_notify
```

{% hint style="info" %}
Start `bl_notify` after your framework
{% endhint %}

**4. Restart Server**

On startup you should see framework detection in the console:

```
[bl_notify] Framework Detected: Qbox
```

If auto detection fails, set `Config.Framework` manually in `config/config.lua`.

#### Manual Framework Replacement

to patch framework files directly, see the guides in:

```
install/replace_qbx.md
install/replace_qb.md
install/replace_esx.md
install/replace_ox.md
```

These show how to redirect native notify calls to `bl_notify:Alert`.

### Usage

#### Client Export

```lua
exports['bl_notify']:Notify(
    'Success',           -- title
    'Action completed.', -- message
    5000,                -- duration (ms)
    'success',           -- type
    'top right'          -- position (optional)
)
```

#### Client Event

```lua
TriggerEvent('bl_notify:Alert', 'Title', 'Message', 5000, 'success', 'top right')
```

From the server:

```lua
TriggerClientEvent('bl_notify:Alert', playerId, 'Title', 'Message', 5000, 'success', 'top right')
```

#### Notify Exports

Sends a notification to a player and logs it to configured providers:

```lua
exports['bl_notify']:Notify(
    playerId,
    'Title',
    'Message',
    5000,
    'success',
    'top right'
)
```

#### Logging Exports

Log without showing a notification:

```lua
exports['bl_notify']:Log(
    playerId,   -- optional; omit or pass nil for server only logs
    'Title',
    'Message',
    'error'
)
```

{% hint style="warning" %}
Logging is **server side only**
{% endhint %}

#### Notification Types

| Type      | Aliases accepted    |
| --------- | ------------------- |
| `success` | —                   |
| `error`   | —                   |
| `info`    | `primary`, `inform` |
| `warning` | `warn`              |
| `neutral` | —                   |

Unknown types fall back to `info`.

#### Positions

Set the default in config or pass per notification:

```
top right
top left
top
bottom right
bottom left
bottom
center right
center left
```

Legacy values like `topright` are also accepted.

### Framework Integration

#### Auto Detection

```lua
Config.Framework = "auto"
```

Detection order:

```
qbx_core  →  Qbox
qb-core   →  QBCore
es_extended  →  ESX
```

#### Manual Framework

```lua
Config.Framework = "qbox"   -- or "qbcore", "esx"
```

#### Replace Native Notifications

```lua
Config.ReplaceQBNotify = true   -- QBCore:Notify
Config.ReplaceOXNotify = true   -- lib.notify
Config.ReplaceESXNotify = true  -- ESX.ShowNotification
```

When enabled, existing framework notify calls automatically use the BL NOTIFY UI without changing other resources.

### Configuration

Main configuration file:

```
config/config.lua
```

#### Example

```lua
Config.Framework = "auto"

Config.ReplaceQBNotify = true
Config.ReplaceOXNotify = true
Config.ReplaceESXNotify = true

Config.Position = 'top right'

Config.TestCommands = {
    enabled = true,
    permissions = { 'bl_notify.admin', 'admin' },
}

Config.types = {
    success = { bg = '#0f5132', border = '#198754', icon = '✓' },
    info    = { bg = '#084298', border = '#0d6efd', icon = 'ℹ' },
    warning = { bg = '#664d03', border = '#ffc107', icon = '!' },
    error   = { bg = '#842029', border = '#dc3545', icon = '✕' },
    neutral = { bg = '#1a1a1a', border = '#6c757d', icon = '●' },
}
```

{% hint style="info" %}
Notification styling in the NUI is primarily controlled through `html/styles.css` and `html/scripts.js`
{% endhint %}

### Server Logging

BL NOTIFY includes optional outbound logging for server owners

#### Supported Providers

* Discord
* Fivemerr
* Fivemanage (HTTP or `fmsdk`)

Configuration file:

```
server/logging.lua
```

#### Configuration

```lua
Logging.Discord = {
    enabled = true,
    url = 'YOUR_DISCORD_WEBHOOK_URL',
    username = 'Notify',
    avatarUrl = '',
    showTypes = { 'error', 'warning', 'success', 'neutral', 'info' },
}

Logging.Fivemerr = {
    enabled = false,
    apiKey = 'YOUR_FIVEMERR_API_KEY',
    resource = '',
    showTypes = { 'error', 'warning', 'success', 'neutral', 'info' },
}

Logging.Fivemanage = {
    enabled = false,
    dataset = 'default',
    useSdk = true,
    apiKey = 'YOUR_FIVEMANAGE_API_KEY',
    showTypes = { 'error', 'warning', 'success', 'neutral', 'info' },
}
```

Each provider supports filtering by notification type via `showTypes`

#### When Logs Are Sent

Logs are sent when you call the server `Notify` or `Log` exports

{% hint style="info" %}
Store API keys and webhook URLs in `server.cfg` 
{% endhint %}

### Test Commands

Admins can open the built in test menu:

```
/notifytest
```

Requires ACE permission configured in `Config.TestCommands.permissions` (default: `bl_notify.admin` or `admin`).

The menu lets you preview each notification type or run **Show All**. Press **ESC** to close.

Disable test commands:

```lua
Config.TestCommands = {
    enabled = false,
    permissions = { 'bl_notify.admin', 'admin' },
}
```

### Escrow

Only `server/version.lua` is escrow protected. The following remain open for editing:

```
config/
shared/
client/
html/
install/
server/console.lua
server/logging.lua
server/framework.lua
server/server.lua
fxmanifest.lua
README.md
```

### Files Structure

```
config/config.lua          → Main configuration
shared/framework.lua       → Framework detection (shared)

client/client.lua          → NUI, hooks, exports, test menu

server/console.lua         → Console output helpers
server/version.lua         → Version checking (escrow)
server/logging.lua         → Discord / Fivemerr / Fivemanage
server/framework.lua       → Server framework detection
server/server.lua          → Test command permissions

html/                      → Notification UI (index, styles, scripts)
install/                   → Framework replacement guides
```

### Troubleshooting

#### Notifications Not Showing

* Ensure `bl_notify` is started
* Check F8 console for NUI errors
* Verify the resource is not stopped or conflicting with another notify resource

#### Qbox / ox\_lib Not Hooked

* Ensure `ox_lib` starts before `bl_notify`
* Confirm `Config.ReplaceOXNotify = true`
* Look for `[bl_notify] lib.notify active` in the client console
* If hook fails, see `install/replace_ox.md` or `install/replace_qbx.md`

#### Framework Not Detected

* Set `Config.Framework` manually instead of `"auto"`
* Ensure your framework resource is started before or with `bl_notify`

#### Wrong Position

* Set `Config.Position` using spaced values: `'top right'` not `'topright'`
* Legacy compact values (`topright`, etc.) are supported

#### Logs Not Appearing

* Use server exports (`Notify` or `Log`), not client events
* Ensure the provider is `enabled = true`
* Verify webhook URL / API keys are set
* Check `showTypes` includes the notification type you are logging
* For Fivemanage SDK mode, ensure `fmsdk` is started

#### `/notifytest` Permission Denied

* Grant ACE permission: `add_ace group.admin bl_notify.admin allow`
* Or add your group to `Config.TestCommands.permissions`

### Purchase Info

This script is free. To get it, please visit our official store.

### Support

Contact our support team on Discord for updates, help, or customization options.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bl-scripts-1.gitbook.io/bl-scripts-docs/bl-notify.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.