Skip to content

Commit ae6683e

Browse files
committed
Docs for new version
1 parent 084ec77 commit ae6683e

File tree

18 files changed

+296
-307
lines changed

18 files changed

+296
-307
lines changed

.idea/docs.iml

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

.idea/misc.xml

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

.idea/modules.xml

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

.idea/vcs.xml

Lines changed: 6 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

docs/configuration.md

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,20 @@ All these variables can be passed to executables as command-line arguments (see
1212
| NOTIFICO_HTTP_INGEST_BIND | :material-check: | Local address for [ingest](components.md#ingest) service. |
1313
| NOTIFICO_WEB_BIND | :material-check: | Local address for [web](components.md#web) service. |
1414
| NOTIFICO_USERAPI_BIND | :material-check: | Local address for [userapi](components.md#user-api) service. |
15-
| NOTIFICO_USERAPI_URL | :material-check: | User-facing address for userapi service |
16-
| NOTIFICO_CREDENTIALS_PATH | | Default: `/var/lib/notifico/credentials.toml` |
15+
| NOTIFICO_USERAPI_URL | :material-check: | User-facing address for userapi service | |
1716

1817
## Credentials
1918

20-
Credentials are stored in TOML format. You can add as many configurations as you need for different services.
19+
Credentials in Notifico are set using environment variables. The format for setting credentials is as follows:
2120

22-
See channels documentation for credential format.
21+
```shell
22+
NOTIFICO_CRED_<NAME>=<TRANSPORT>:<VALUE>
23+
```
24+
25+
Where:
26+
27+
- `<NAME>` is the name of the credential. This name is converted into lowercase.
28+
- `<TRANSPORT>` is the transport name
29+
- `<VALUE>` is the actual credential value
30+
31+
For more detailed information about credential formats and their usage with specific plugins, please refer to the [Plugins](plugins/core.md) section of the documentation.

docs/notificox.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# NotificoX
2+
3+
[![GitHub Release](https://img.shields.io/github/v/release/notificohq/notifico?style=for-the-badge)](https://github.com/notificohq/notifico/releases/latest)
4+
5+
NotificoX is a versatile tool designed to send messages to various services, inspired by the popular notification library, [Apprise](https://github.com/caronc/apprise).
6+
It provides a unified interface to deliver notifications across multiple platforms, making it easier for users to manage and automate their communication needs.
7+
8+
With NotificoX, you can send messages to a wide range of channels, including email, SMS, and instant messaging services.
9+
10+
This tool is a single dependency-free binary (only libc and SSL library are required), so you can run it anywhere,
11+
for example in CI pipelines.
12+
13+
Some arguments are formatted in [JSON5](https://json5.org/), so they can be entered without numerous escape sequences.
14+
15+
## Send notification locally
16+
**Usage:**
17+
```shell
18+
notificox send --channel <CHANNEL> --template <TEMPLATE> <CREDENTIAL> [CONTACTS]...
19+
```
20+
21+
**Where:**
22+
23+
- CHANNEL: the channel of notification. You can find relevant channels in [PLugins](plugins/core.md) section of this documentation.
24+
- TEMPLATE: JSON5-formatted message template object. Template parameters are channel-specific.
25+
- CREDENTIAL: string-formatted transport credential
26+
- CONTACTS: zero or more contacts to send the message. Contact format is transport-specific. Some channels, like Gotify don't require contacts, as they only use credentials to send.
27+
28+
This command internally constructs a Notifico [pipeline](pipeline.md) and executes it using the embedded pipeline engine.
29+
This process is fully transparent to end user.
30+
31+
## Trigger an event on remote Notifico Ingest service
32+
**Usage:**
33+
```shell
34+
notificox send-event [OPTIONS] --ingest <INGEST> <EVENT> <CONTEXT>
35+
```

docs/plugins/core.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Core plugin
22

3-
## Step: `core.set_recipients`
3+
## Steps
4+
### Step: `core.set_recipients`
45

56
```json
67
{
@@ -16,7 +17,6 @@
1617

1718
Where `RECIPIENT` is a recipient entity. See [Recipient](../recipient.md) for more info.
1819

19-
### How this works under hood:
20+
## How this works under hood
2021
The Pipeline is forked in the runtime, preserving the current pipeline context.
21-
The forked pipelines start from the following step. This step creates a pipeline for every contact, matching current
22-
pipeline's channel for every recipient, resulting in `Recipients * Contacts` pipelines.
22+
The forked pipelines start from the following step. This step creates a pipeline for every recipient, resulting in `Recipients` pipelines.

docs/plugins/pushover.md

Lines changed: 12 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,26 @@
11
# Pushover
22

3-
**Channel identifier:** `pushover`
3+
**Contact:** `pushover:USER_KEY`
44

5-
## Quick example
6-
`POST /api/v1/send`
7-
```json
8-
{
9-
"event": "YOUR_EVENT_NAME",
10-
"recipients": [
11-
{
12-
"id": "3766b9e9-a700-4c75-a9c9-88117af11767",
13-
"contacts": [
14-
{
15-
"type": "pushover",
16-
"user": "RECIPIENT_USER_KEY"
17-
}
18-
]
19-
}
20-
],
21-
"context": {
22-
"beans_count": 4815162342
23-
}
24-
}
25-
```
5+
**Credential:** `pusoover:API_TOKEN`
266

27-
## Step: `pushover.send`
28-
```json
29-
{
30-
"step": "pushover.send",
31-
"credential": "CREDENTIAL_NAME"
32-
}
33-
```
7+
**Channel:** `pushover`
348

359
## Template parameters
36-
- `text` parameter defines the body of Pushover message.
37-
- `title` defines the title, displayed in Push notification.
38-
```toml
39-
text = "You have {{ beans_count }} magic beans"
40-
title = "Hello!"
10+
```yaml
11+
body: "Template {{ parameter }}" # body of Pushover message
12+
title: "Title" # title, displayed in Push notification
4113
```
4214
43-
## Contact
44-
[Recipient](../recipient.md) Contact format for Pushover integration:
15+
## Steps
16+
### Step: `pushover.send`
4517
```json
4618
{
47-
"type": "pushover",
48-
"user": "USER_KEY"
19+
"step": "pushover.send",
20+
"credential": "CREDENTIAL_NAME"
4921
}
5022
```
5123

52-
## Credentials
24+
## Connecting to Pushover
5325
To configure your Pushover account, you have to create a new application [here](https://pushover.net/apps/build).
54-
You will get "API Token", that you can add to your `credentials.toml` file:
55-
56-
```toml
57-
[pushover.CREDENTIAL_NAME]
58-
token = "YOUR_PUSHOVER_TOKEN"
59-
```
60-
61-
Replace `CREDENTIAL_NAME` with a credential name, that will be used for referencing this credential in pipelines (see above).
26+
You will get "API Token", that you use in credential.

docs/plugins/slack.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# Slack
22

3-
**Channel identifier:** `slack`
3+
**Contact:** `slack:CHANNEL_ID`
4+
5+
**Credential:** `slack:API_TOKEN`
6+
7+
**Channel:** `slack`
48

59
## Step: `slack.send`
610
```json

docs/plugins/smpp.md

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,13 @@
11
# SMPP (Short Message Peer-to-Peer Protocol)
22

3-
**Channel identifier:** `sms`
3+
**Contact:** `mobile_phone:PHONE`
44

5-
SMPP is a protocol used by the telecommunications industry for exchanging SMS messages between Short Message Service Centers (SMSC) and External Short Messaging Entities (ESME).
5+
**Credential:** `smpp:SYSTEM_ID:PASSWORD@HOST:PORT`
66

7-
Many SMS Center services allow SMPP protocol for sending SMS.
7+
**Channel:** `sms`
88

9-
To configure an SMPP server, add the following section to your `credentials.toml` file:
9+
SMPP is a protocol used by the telecommunications industry for exchanging SMS messages between Short Message Service Centers (SMSC) and External Short Messaging Entities (ESME).
1010

11-
```toml
12-
[smpp.<NAME>]
13-
host = "smpp.example.com"
14-
port = 2775
15-
username = "your_username"
16-
password = "your_password"
17-
```
11+
Many SMS Center services allow SMPP protocol for sending SMS.
1812

1913
Note: We don't support TLS for SMPP right now. This will be added in future releases.

0 commit comments

Comments
 (0)