@jackdbd/hapi-telegram-plugin

Hapi plugin that sends a message to a Telegram chat when a request matches one of the rules you defined.

Table of Contents

• Installation
• Preliminary Operations
  • Create a Telegram bot with BotFather
• Usage
• Configuration
  • Options

Installation

npm install @jackdbd/hapi-telegram-plugin

Preliminary Operations

Create a Telegram bot with BotFather

A Telegram bot is an API that implements webhooks. When you create a Telegram bot with BotFather, Telegram creates an API on its servers. You can then make HTTP requests to this API.

This Hapi plugin makes a POST request to the /sendMessage endpoint whenever there is an error in your request handlers.

Create a Telegram bot with the following steps:

1. Open a Telegram chat with BotFather and enter the /newbot command.
2. Choose a name and a username for your bot. The name can be anything and you can change it any time. The username is unique, you cannot change it, and must end with _bot. Write down the bot token that BotFather returns you.

:information_source: You can see your Telegram bot token at any time:

1. open a chat with BotFather
2. enter the /mybots command
3. select the bot you are interested in
4. click API token

See also the ufficial Telegram documentation:

• Bots: An introduction for developers.
• sendMessage API endpoint.
• message formatting options. A Telegram message can be 1-4096 characters long, after entities parsing.

Usage

You define request rules like this one:

{
  name: 'notify me of any server error (e.g. internal server error)',
  chat_id: 'YOUR-TELEGRAM-CHAT-ID',
  token: 'YOUR-TELEGRAM-BOT-TOKEN',
  predicate: isServerRequestError,
  text: serverError
}

...and this plugin sends a Telegram message like this one:

Let's say that you want to receive notifications for server errors (i.e. HTTP 5xx), and notifications for unauthorized errors (i.e. HTTP 401). You would configure the plugin like this:

import telegram from '@jackdbd/hapi-telegram-plugin'
import type {
  Options as TelegramPluginOptions
} from '@jackdbd/hapi-telegram-plugin'

// define your request predicates somewhere in your app,
// or import them from a library.
import {
  isServerRequestError,
  isUnauthorizedRequestError
} from '@jackdbd/hapi-request-event-predicates'

// define the functions that create the text string to
// send to Telegram, or import them from a library.
import {
  serverError,
  unauthorized
} from '@jackdbd/hapi-telegram-plugin/texts'


export const app = async (config) => {

  const server = Hapi.server({ port: 8080 })

  server.log(['lifecycle'], {
    message: `HTTP server created.`
  })

  const options: TelegramPluginOptions = {
    // when a request to your Hapi app matches a rule, this plugin
    // sends a message to the Telegram chat specified in that
    // particular rule.
    request_event_matchers: [
      {
        name: 'notify of server errors',
        chat_id: 'YOUR-TELEGRAM-CHAT-ID',
        token: 'YOUR-TELEGRAM-BOT-TOKEN',
        predicate: isServerRequestError,
        text: serverError
      },
      {
        name: 'warn about HTTP 401 (Unauthorized) request errors',
        chat_id: 'YOUR-TELEGRAM-CHAT-ID',
        token: 'YOUR-TELEGRAM-BOT-TOKEN',
        predicate: isUnauthorizedRequestError,
        text: unauthorized
      }
    ]
  }

  await server.register({ plugin: telegram, options })

  server.log(['lifecycle', 'plugin'], {
    message: `Telegram plugin registered.`
  })

  return { server }
}

Configuration

Options

Option	Default	Explanation
request_event_matchers	see defaultRequestEventMatchers() in register.ts	Each rule controls which request matches, and to which Telegram chat the text should be sent.