@jhb0430/telegram

텔레그램 봇으로 텍스트 한 통을 보내는 클라이언트입니다.

봇 토큰과 채팅방 ID를 넣고 sendMessage를 호출하면 끝입니다. 사진, 답장, 토픽, 로그 릴레이 서버는 없습니다.

설치

npm install @jhb0430/telegram

NestJS는 선택입니다. Nest를 쓰지 않으면 @nestjs/common이 없어도 됩니다.

환경 변수

프로세스에 아래 세 값이 있으면 됩니다.

| 변수 | 값 | |------|-----| | TELEGRAM_ENABLED | true 또는 1 이면 전송. false / 0 이면 보내지 않음 | | TELEGRAM_BOT_TOKEN | BotFather가 준 토큰 | | TELEGRAM_CHAT_ID | 메시지를 받을 채팅방 ID |

채팅방 ID는 봇에게 /start를 보낸 뒤 https://api.telegram.org/bot<토큰>/getUpdates의 message.chat.id입니다.

프로젝트마다 키 이름이 다르면 envKeys로 넘깁니다. 아래 「다른 키 이름」을 보세요.

보내기

import { TelegramBotClient } from '@jhb0430/telegram';

const telegram = new TelegramBotClient();

const result = await telegram.sendMessage('서버가 시작되었습니다.');
if (result.delivered) {
  // 채팅방에 도착함
} else {
  // result.reason, result.status 를 로그에 남기면 됩니다.
}

sendMessage는 예외를 던지지 않습니다. 알림 실패가 요청 처리를 막지 않게 하기 위해서입니다.

| result | 의미 | |----------|------| | delivered: true | Bot API가 성공으로 응답함 | | delivered: false, reason: 'not_configured' | 꺼져 있거나 토큰·채팅방 ID가 없음 | | delivered: false, reason: 'http_error', status: 401 | 토큰이 틀리거나 봇이 그 방에 없음 | | delivered: false, reason: 'request_failed' | 타임아웃·네트워크 오류. status는 없음 |

토큰 문자열은 결과와 로그에 넣지 않습니다.

설정만 확인할 때는 telegram.isConfigured()를 쓰면 됩니다.

굵은 글씨

전송은 항상 텔레그램 HTML 모드입니다. 호출자가 넣은 <b>, <i>, <code>, <pre>, <a href="https://..."> 는 태그로 두고, 그 사이 본문의 <, >, & 만 이스케이프합니다.

const text = telegram.formatHtml([
  '🚨 <b>[prod] API 500</b>',
  '<b>GET</b> /health',
  'detail: a < b & c',
]);
await telegram.sendMessage(text);

채팅에는 제목과 GET이 굵게 나오고, a < b & c는 글자로 보입니다. <script>처럼 허용되지 않은 태그는 글자 그대로 이스케이프됩니다.

빈 줄과 null은 빠집니다.

코드로 토큰 넘기기

env 대신 파일·설정 객체에 토큰이 있으면 fileFallback에 넣습니다. env가 있으면 env가 우선입니다.

const telegram = new TelegramBotClient({
  fileFallback: {
    enabled: true,
    botToken: config.telegram.botToken,
    chatId: config.telegram.chatId,
  },
});

다른 키 이름

기본 키를 쓰지 않는 프로젝트는 이름을 지정합니다.

const telegram = new TelegramBotClient({
  envKeys: {
    enabled: 'TELEGRAM_DEV_ALERTS_ENABLED',
    botToken: 'TELEGRAM_DEV_BOT_TOKEN',
    chatId: 'TELEGRAM_DEV_CHAT_ID',
  },
});

NestJS

import { Module } from '@nestjs/common';
import { TelegramModule, TelegramBotService } from '@jhb0430/telegram';

@Module({
  imports: [
    TelegramModule.forRoot({
      fileFallback: {
        enabled: true,
        botToken: process.env.TELEGRAM_BOT_TOKEN,
        chatId: process.env.TELEGRAM_CHAT_ID,
      },
    }),
  ],
})
export class AppModule {}

// 다른 서비스에서 주입
constructor(private readonly telegram: TelegramBotService) {}

await this.telegram.sendMessage('안녕하세요');

TelegramBotService.sendMessage의 반환값은 TelegramBotClient와 같습니다.

부팅 전에 env 파일 읽기

.env 파일을 프로세스에 올린 뒤 앱을 띄울 때 씁니다. TELEGRAM_으로 시작하는 키만 읽습니다.

TELEGRAM_ENV_FILE=/path/to/telegram.env node -r @jhb0430/telegram/preload dist/main.js

이 preload는 CONFIG_SOURCE 같은 다른 설정을 바꾸지 않습니다. 파일이 없으면 아무 것도 하지 않습니다.

예시 파일은 패키지 안의 config/telegram.env.example입니다.