Skip to main content
Plugins / Telegram

Telegram

by appleboy

Plugin for sending Telegram notifications

The Telegram plugin posts build status messages to your account. The below pipeline configuration demonstrates simple usage:

- name: send telegram notification
  image: appleboy/drone-telegram
  settings:
    token: xxxxxxxxxx
    to: telegram_user_id

Example configuration with photo message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     photo:
+       - tests/1.png
+       - tests/2.png

Example configuration with document message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     document:
+       - tests/1.pdf
+       - tests/2.pdf

Example configuration with sticker message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     sticker:
+       - tests/3.png
+       - tests/4.png

Example configuration with audio message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     audio:
+       - tests/audio1.mp3
+       - tests/audio2.mp3

Example configuration with voice message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     voice:
+       - tests/voice1.ogg
+       - tests/voice2.ogg

Example configuration with location message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     location:
+       - 24.9163213,121.1424972
+       - 24.9263213,121.1224972

Example configuration with venue message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     venue:
+       - 24.9163213,121.1424972,title,address
+       - 24.3163213,121.1824972,title,address

Example configuration with video message:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     video:
+       - tests/video1.mp4
+       - tests/video2.mp4

Example configuration with message format (Markdown or HTML), default as Markdown:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     format: Markdown

Example configuration with a custom message template:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     message: >
+       {{#success build.status}}
+         build {{build.number}} succeeded. Good job.
+       {{else}}
+         build {{build.number}} failed. Fix me please.
+       {{/success}}

Example configuration with a custom message template loaded from file:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     message_file: message_file.tpl

Example configuration with a generic message template loaded from file, with additional extra vars:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     message_file: message_file.tpl
+     template_vars:
+       env: testing
+       app: MyApp

Where message_file.tpl is:

Build finished for *{{tpl.app}}* - *{{tpl.env}}*

{{#success build.status}}
  build {{build.number}} succeeded. Good job.
{{else}}
  build {{build.number}} failed. Fix me please.
{{/success}}

Example configuration with a custom message template, with extra vars loaded from file (e.g. from previous build steps):

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
+     template_vars_file: build_report.json
+     message: >
+       {{#success build.status}}
+         build {{build.number}} succeeded, artefact version = {{tpl.artefact_version}}.
+       {{else}}
+         build {{build.number}} failed. Fix me please.
+       {{/success}}

Where build_report.json is:

{
  ...
  "artefact_version": "0.2.3452"
  ...
}

Example configuration with a custom socks5 URL:

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
      message: send message using custom socks5 URL
+     socks5: socks5://67.204.21.1:64312

Disables link previews for links in this message

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
      message: send message without a link preview
+     disable_web_page_preview: true

Disables notifications for this message

  - name: send telegram notification
    image: appleboy/drone-telegram
    settings:
      token: xxxxxxxxxx
      to: telegram_user_id
      message: send message message silently
+     disable_notification: true

Parameter Reference

token : telegram token from telegram developer center

to : telegram user id (can be requested from the @userinfobot inside Telegram)

message : overwrite the default message template

message_file : overwrite the default message template with the contents of the specified file

template_vars : define additional template vars. Example: var1: hello can be used within the template as tpl.var1

template_vars_file : load additional template vars from json file. Example: given file content {"var1":"hello"}, variable can be used within the template as tpl.var1

photo : local file path

document : local file path

sticker : local file path

audio : local file path

voice : local file path

location : local file path

video : local file path

venue : local file path

format : markdown or html format

Template Reference

repo.owner : repository owner

repo.name : repository name

commit.sha : git sha for current commit

commit.branch : git branch for current commit

commit.link : git commit link in remote

commit.author : git author for current commit

commit.email : git author email for current commit

commit.message : git current commit message

build.status : build status type enumeration, either success or failure

build.event : build event type enumeration, one of push, pull_request, tag, deployment

build.number : build number

build.tag : git tag for current commit

build.link : link the the build results in drone

build.started : unix timestamp for build started

build.finished : unix timestamp for build finished

Template Function Reference

uppercasefirst : converts the first letter of a string to uppercase

uppercase : converts a string to uppercase

lowercase : converts a string to lowercase. Example {{lowercase build.author}}

datetime : converts a unix timestamp to a date time string. Example {{datetime build.started}}

success : returns true if the build is successful

failure : returns true if the build is failed

truncate : returns a truncated string to n characters. Example {{truncate build.sha 8}}

urlencode : returns a url encoded string

since : returns a duration string between now and the given timestamp. Example {{since build.started}}