# pm2-telegram

> Telegram notifications for PM2 process manager

Latest version **0.2.4** (published 2022-07-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install pm2-telegram
pnpm add pm2-telegram
yarn add pm2-telegram
bun add pm2-telegram
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.4 |
| Published | 2022-07-01 |
| First published | 2022-04-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 20.6 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Ivan Tsybanenko |
| Maintainers | trumanru |
| Keywords | pm2, telegram |

## Links

- npm: https://www.npmjs.com/package/pm2-telegram
- Repository: https://github.com/TrumanRu/pm2-telegram
- Homepage: https://github.com/TrumanRu/pm2-telegram#readme
- Issues: https://github.com/TrumanRu/pm2-telegram/issues
- npm.io page: https://npm.io/package/pm2-telegram

## Dependencies (2)

- [pm2](https://npm.io/package/pm2.md) ^5.2.0
- [pmx](https://npm.io/package/pmx.md) ^1.2.0

## Recent versions

- 0.2.4 (latest) — 2022-07-01
- 0.2.3 — 2022-04-22
- 0.2.2 — 2022-04-22
- 0.2.1 — 2022-04-22
- 0.2.0 — 2022-04-22
- 0.1.12 — 2022-04-15
- 0.1.11 — 2022-04-15
- 0.1.10 — 2022-04-15
- 0.1.9 — 2022-04-15
- 0.1.8 — 2022-04-14
- 0.1.7 — 2022-04-13
- 0.1.6 — 2022-04-13
- 0.1.5 — 2022-04-12
- 0.1.4 — 2022-04-12
- 0.1.3 — 2022-04-12
- … 7 more at https://npm.io/package/pm2-telegram/versions

## README

[![npm package](https://img.shields.io/npm/v/pm2-telegram?logo=npm&style=for-the-badge)](https://www.npmjs.com/package/pm2-telegram) [![GitHub issues](https://img.shields.io/github/issues/TrumanRu/pm2-telegram?logo=github&label=GitHub%20issues&style=for-the-badge)](https://github.com/TrumanRu/pm2-telegram/issues)

# pm2-telegram

**Telegram notifications for PM2 process manager**

## Functions

* collect desired messages to buffer then send collected messages every 10 seconds
* allow messages scope selection (errors, logs, exceptions and kill events)
* truncate long messages (longer than Telegram limitation 4096 characters) to avoid send error
* combine short messages to one message (the resultant big message shorter than 4096 characters) to avoid impact of Telegram messages frequency limitation (see: [My bot is hitting limits, how do I avoid this?](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this))
* set message title for _pm2-telegram_ instance to distinguish messages from one Telegram bot installed on many instances (default is server hostname)
* format messages for better viewing (be aware to face with Markdown characters in raw notification text!)

#### Examples
###### Unformatted
![Unformatted message example](https://raw.githubusercontent.com/TrumanRu/cdn/HEAD/pm2-telegram/message-unformatted.jpg "Unformatted message")
###### Formatted
![Formatted message example](https://raw.githubusercontent.com/TrumanRu/cdn/HEAD/pm2-telegram/message-formatted.jpg "Formatted message")

#### Roadmap

* *(under development)* option to split long messages to many continuous messages (you should choose truncate or split big messages)
* *(under development)* option to display real message's timestamp and set timestamp format (HH:mm:ss.SSS)
* *(under development)* control messages buffer overflow, reset it and send buffer overflow notification

## Setup

### Create bot

* create a Telegram bot with Telegram's BotFather (look at [Telegram documentation](https://core.telegram.org/bots#creating-a-new-bot))
* get BOT_TOKEN from BotFather's answer

### Get chat id

* add the bot to a group if you want to send notifications to a group
* send message from group to the bot: `/test Hello bot!` (use any command-like message started by slash)
* open sent message at `https://api.telegram.org/bot<BOT_TOKEN>/getUpdates`

```javascript
{
    "ok": true,
    "result": [{
            "update_id": 123456789,
            "message": {
                "message_id": 1,
                "from": {
                    "id": 223322223322,
                    "is_bot": false,
                    "first_name": "Hildur",
                    "last_name": "Bock",
                    "username": "fröken_bock"
                },
                "chat": {
                    "id": -76543210, // <- this is chat_id!
                    "title": "Buns_Eaters",
                    "type": "group",
                    "all_members_are_administrators": false
                },
                "date": 1649627436,
                "text": "/test Hello bot!",
                "entities": [{
                        "offset": 0,
                        "length": 5,
                        "type": "bot_command"
                    }
                ]
            }
    }]
}
```
CHAT_ID is on `result.message.chat.id` property.

###### Notice:

> If you in the first created a group with only you and a bot, but later you'll add a second real user `chat.id` could be changed by Telegram. Check `chat.id` after add the second real user!

### Start module

* install the module: `pm2 install pm2-telegram`
* set the bot token: `pm2 set pm2-telegram:bot_token <BOT_TOKEN>`
* set chat id: `pm2 set pm2-telegram:chat_id <CHAT_ID>`

> For a group's chat id prepend it by `g-` to isolate minus sign, eg:
>   <br>group chat _CHAT_ID_ = `-76543210` -> `g-76543210`
>   <br>personal chat _CHAT_ID_ = `123456789` -> `123456789`

## Configure notifications

* to set any option use: `pm2 set pm2-telegram:<OPTION_NAME> <OPTION_VALUE>`

#### Notification options

| option name   | default | description                        |
|---------------|---------|------------------------------------|
| **error**     | true    | console.error() and console.warn() |
| **log**       | false   | console.log()                      |
| **kill**      | true    | kill PM2 process                   |
| **exception** | true    | exception in PM2 process           |

#### Module behavior options

| option name | default | description                                    |
|-------------|---------|------------------------------------------------|
| **collate** | true    | combine short messages to one Telegram message |

#### Module description options

| option name     | default            | description                                                                                                            |
|-----------------|--------------------|------------------------------------------------------------------------------------------------------------------------|
| **title**       | _server host name_ | messages title (could be used for set server name)                                                                     |
| **text_format** | _undefined_        | 'Markdown' to format messages (be careful if your messages could have Markdown format characters - there'll lost them) |

#### Full configuration example

```bash
pm2 set pm2-telegram:title OnTheRoof
pm2 set pm2-telegram:bot_token 223322223322:ABCDefghIJKLmnop12345rStUvWxYz67890
pm2 set pm2-telegram:chat_id g-76543210
pm2 set pm2-telegram:error true
pm2 set pm2-telegram:text_format Markdown
pm2 install pm2-telegram
```

#### Reset option
Use `set` operator without a value to reset option.

For example to clear `text_format` option value use: `pm2 set pm2-telegram:text_format`

## Upgrade module to the latest version

```bash
pm2 install pm2-telegram@latest
```

---

## Notices

#### Bugs and feature requests

Welcome to [GitHub Issues](https://github.com/TrumanRu/pm2-telegram/issues)!

#### Thanks for some ideas to:

* [shubhroshekhar](https://github.com/shubhroshekhar/) (author of [pm2-telegram-notification](https://github.com/shubhroshekhar/pm2-telegram-notification))
* [korolyov88](https://github.com/korolyov88/pm2-telegram-notify) (author of [pm2-telegram-notify](https://github.com/korolyov88/pm2-telegram-notify))

## Releases

| version    | changes                                                                                                                                                                                 |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **0.2.4**  | • _fix_: remove extra debug message                                                                                                                                                     |
| **0.2.3**  | • _docs_: remove documentation images from project                                                                                                                                      |
| **0.2.2**  | • _docs_: documentation corrections                                                                                                                                                     |
| **0.2.1**  | • _docs_: minimize example's image files size                                                                                                                                           |
| **0.2.0**  | • _feature_: add option `text_format` to format notification messages<br/>• _fix_: mistaken truncate messages on `&` character                                                          |
| **0.1.12** | • _docs_: documentation update                                                                                                                                                          |
| **0.1.11** | • _feature:_ set default `title` as local server hostname (on upgrade don't forget to call `pm2 set pm2-telegram:title` with empty value to reset value stored in PM2 'title' variable) |
| **0.1.10** | • _docs_: documentation update                                                                                                                                                          |
| **0.1.9**  | • _fix:_ message type missed in notification title ('error', 'exception' etc.) and in messages delimiters (new lines)                                                                   |
| **0.1.8**  | • _fix:_ error on send exception message (message is 'undefined')                                                                                                                       |

---
_Source: https://npm.io/package/pm2-telegram · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
