woltsu/telegram-orb

Create custom Telegram notifications in CircleCI

telegram-orb

Easily integrate custom Telegram notifications into your CircleCI projects.

Learn more about Orbs.

Usage

Example config:

version: 2.1

orbs:
  telegram: woltsu/[email protected]

jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - telegram/<command>

Commands

Notify

Notify a Telegram channel with a custom message at any point in a job with this custom step.

Parameter	Type	Default	Description
message	string	Message from CircleCI.	Enter a custom message.
telegram-bot-token	env_var_name	TELEGRAM_BOT_TOKEN	Name of environment variable storing your Telegram bot token
telegram-chat-id	env_var_name	TELEGRAM_CHAT_ID	Name of environment variable storing your Telegram chat id
parse_mode	string	none	Use Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message.
disable_notification	boolean	none	Sends the message silently. Users will receive a notification with no sound.

Example:

version: 2.1

orbs:
  telegram: woltsu/[email protected]

jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - telegram/notify:
          message: "Notification from CircleCI!"

GetMe

A simple method for testing your bot's auth token. Returns basic information about the bot in form of a User object.

Parameter	Type	Default	Description
telegram-bot-token	env_var_name	TELEGRAM_BOT_TOKEN	Name of environment variable storing your Telegram bot token

Example:

version: 2.1

orbs:
  telegram: woltsu/[email protected]

jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - telegram/getme

GetChat

A method to get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.) Returns a Chat object on success.

Parameter	Type	Default	Description
telegram-bot-token	env_var_name	TELEGRAM_BOT_TOKEN	Name of environment variable storing your Telegram bot token
telegram-chat-id	env_var_name	TELEGRAM_CHAT_ID	Name of environment variable storing your Telegram chat id

Example:

version: 2.1
orbs:
  telegram: woltsu/[email protected]
jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - telegram/getchat

SendSticker

Send a sticker to Telegram

Parameter	Type	Default	Description
telegram-bot-token	env_var_name	TELEGRAM_BOT_TOKEN	Name of environment variable storing your Telegram bot token
telegram-chat-id	env_var_name	TELEGRAM_CHAT_ID	Name of environment variable storing your Telegram chat id
telegram-sticker	string	""	file_id or url to .webp

Example:

version: 2.1

orbs:
  telegram: woltsu/[email protected]

jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - telegram/sendSticker:
          telegram-sticker: "https://www.example.com/img.webp"

SendGIF

A command which sends an animated image to the specified Telegram chat.

Parameter	Type	Default	Description
telegram-bot-token	env_var_name	TELEGRAM_BOT_TOKEN	Name of environment variable storing your Telegram bot token
telegram-chat-id	env_var_name	TELEGRAM_CHAT_ID	Name of environment variable storing your Telegram chat id
gif-url	string		Enter the image's URL

Example:

version: 2.1

orbs:
  telegram: woltsu/[email protected]

jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - telegram/sendgif:
          gif-url: "https://www.example.com/img.gif"

SendPhoto

A command which sends an image to the specified Telegram chat.

Parameter	Type	Default	Description
telegram-bot-token	env_var_name	TELEGRAM_BOT_TOKEN	Name of environment variable storing your Telegram bot token
telegram-chat-id	env_var_name	TELEGRAM_CHAT_ID	Name of environment variable storing your Telegram chat id
image-url	string		Enter the image's URL

Example:

version: 2.1

orbs:
  telegram: woltsu/[email protected]

jobs:
  build:
    docker:
      - image: <docker image>
    steps:
      - telegram/sendphoto:
          image-url: "https://www.example.com/img.jpg"

Jobs

Notify

Notify a Telegram channel.

Parameter	Type	Default	Description
message	string	Job Message from CircleCI!	Enter a custom message.
telegram-bot-token	env_var_name	TELEGRAM_BOT_TOKEN	Name of environment variable storing your Telegram bot token
telegram-chat-id	env_var_name	TELEGRAM_CHAT_ID	Name of environment variable storing your Telegram chat id
parse_mode	string	none	Use Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message.
disable_notification	boolean	none	Sends the message silently. Users will receive a notification with no sound.

Example:

version: 2.1

orbs:
  telegram: woltsu/[email protected]

jobs:
  - telegram/notify:
      message: "Notification from CircleCI!"

Help

How to create a Telegram bot

https://core.telegram.org/bots

How To Get A Chat Id

https://stackoverflow.com/questions/32423837/telegram-bot-how-to-get-a-group-chat-id

Remember to add your bot into the channel!

How to setup CircleCI environment

In the settings page for your project on CircleCI, click Environment Variables. There you need to add 2 variables: TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID.

telegram-orb's Issues

"sendSticker" command to send a sticker

https://core.telegram.org/bots/api#sendsticker

Add missing parameters to notify command

You can see all available parameters here: https://core.telegram.org/bots/api#sendmessage

Currently we are using message and parse_mode. Remember to update https://github.com/woltsu/telegram-orb/blob/master/src/jobs/notify.yml and README as well.

"sendPhoto" command to send a photo by url

https://core.telegram.org/bots/api#sendphoto

Use sendChatAction to show the status of a circle ci build

https://core.telegram.org/bots/api#sendchataction

Currently there is no feedback if a http request in commands fail

Add proper error handling if api requests fail. F.ex. echo the error or something

Possibility to send a gif

It would be cool to be able to send gifs.

https://core.telegram.org/bots/api#sendanimation

"getChat" command to get information about the target chat

https://core.telegram.org/bots/api#getchat

A job that sends relevant information about the current build to telegram

Here are some env variables provided by CircleCI: https://github.com/circleci/circleci-docs/blob/master/jekyll/_cci1/environment-variables.md. It would also be great if the user could pick the information they'd like to see.

Params validation

Currently the commands assume that the env variables exist. Some validation would be neat.