Telegram 機器人說明，並為你的 Drone CI/CD 配置 Telegram 機器人

Thu, 25 Aug 2022 00:00:00 +0000

參考網站 - Telegram 聊天機器人原理
 參考網站 - 向 @BotFather 申請一隻機器人吧！
參考網站 - Telegram 機器人的設定
 參考網站 - CI/CD trigger WebHook to Telegram Bot
參考網站 - How to setup a Telegram bot for your Drone CI/CD builds

Telegram 聊天機器人原理

機器人的運作原理

現在你發了一段訊息給機器人
但是並不是機器人直接回你訊息

詳細情況如下圖：

一開始你的訊息會被傳送到 TG 伺服器
TG 伺服器會通知機器人：欸！有一則新訊息
機器人會發一個指令給 TG 伺服器
TG 伺服器照著指令的需求，回應訊息給你

機器人接收訊息的兩種模式

機器人可以放在伺服器，也可以用客戶端的方式運作

Webhook
以 伺服器 方式被動接收訊息，需要有 IP 位置，通常會放在 網站伺服器(Web Hosting) 上，要自己架設網站伺服器不是件容易的事，所以官方還提供了另一種做法
Long Polling。
以 客戶端 方式主動跟 TG 伺服器要訊息，可以直接 在自己電腦上運作，不需要架(租)伺服器也能讓機器人順利運作，缺點就是電腦要一直開著，當然你也可以使用 雲端服務(IaaS、PaaS、SaaS)。

機器人發送訊息的三種方式

HTTP GET

1

https://api.telegram.org/bot{Token}/{Method}?{Parameter1}={Value1}&{Parameter2}={Value2}

直接以 網址參數 的方式傳送指令，GET 沒有 Body，只傳送 Headers (你可以當作不會傳送檔案過去)，通常是用來取資料用，優點是可以直接用瀏覽器執行，缺點是有 2KB 的限制，雖然不太可能用到這長的指令，但還是比較建議使用 POST。

HTTP POST

1

{"method":"Method","Parameter1":"Value1","Parameter2":"Value2"}

POST 是 以 Body 傳送資料(檔案)，程式通常都是以這種方式溝通，網頁裡的表單也經常是以這種方式傳送，資料不會顯示在網址列，可以傳送的資料大小比 GET 大得多：1MB ~ 2GB。

直接 Print

這個方式 只有在 webhook 模式 下才能使用，因為只有伺服器可以直接回應訊息。

向 `@BotFather` 申請一隻機器人吧！

The BotFather

The Botfather 這個名字是致敬 1972 年的美國電影《教父》

它是機器人，也是機器人的管理者
幾乎所有機器人的設定、建立都要透過他
用機器人設定機器人聽起來就很有趣，對吧？

@BotFather 的功能

私訊 @BotFather ，按「開始」後就會顯示出一大堆指令，真是令人眼花撩亂

官方網頁版說明

簡單介紹幾個比較常用的功能：

指令	說明
/newbot	建立一個新的機器人
/mybots	列出所有機器人，用按鈕的方式設定機器人，而非指令（這樣可以讓聊天紀錄變得很乾淨，我比較喜歡用這個）
修改相關
/setname	修改顯示名稱
/setdescription	修改說明
/setabouttext	修改簡介
/setuserpic	修改大頭貼
/setcommands	修改指令選單
/deletebot	刪除機器人
設定相關
/token	顯示機器人的 token
/revoke	產生新的 token，舊的會失效
/setjoingroups	設定是否能被加入群組
/setprivacy	設定是否能讀取所有聊天室訊息（機器人的訊息除外，機器人不論如何都不會看到機器人的訊息）

建立你的機器人吧

輸入 /newbot 指令

幫機器人取名字

1

Alright, a new bot. How are we going to call it? Please choose a name for your bot.

這邊它會要你幫你的機器人取一個名字，這個以後能修改，所以隨便取沒差

設定 username

1

Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.

⚠️ 注意：設定後就不能修改了，請謹慎思考之後設定，避免反悔時需要請使用者遷移

需要幫你的機器人設定一個 username，必須符合以下規則：

不需要打 @
以 a~z 開頭
以 bot 結尾
只能使用 a~~z、0~~9 和底線
最小長度為 5 個字元

顯示時會區分大小寫，使用時不區分大小寫（例如設定成 @TetrisBot，用 @tETrISbOt 一樣會指到同一個機器人）

常見問題：

不能以數字開頭

1

Sorry, this username is invalid.

不能用 bot 以外的字結尾

1

Sorry, the username must end in 'bot'. E.g. 'Tetris_bot' or 'Tetrisbot'

username 已經被別人先用走了

1

Sorry, this username is already taken. Please try something different.

出現 Done 表示你設定成功了

使用你的機器人吧

現在你已經可以使用機器人了

按下說明裡的連結(t.me/ironman2021_by_miku3920_bot 點你自己的)，並且點擊「開始」

然後你就會發現什麼事情都沒發生，因為我們還沒寫機器人的程式嘛

不過就算不寫程式也可以讓它說話，利用 HTTP GET 方法，與 sendMessage 這個 API

1

https://api.telegram.org/bot{Token}/{Method}?{Parameter1}={Value1}&{Parameter2}={Value2}

Token：1985044907:AAEdySrbzTc8tVdBjfymlfyaBUJGeu7r-v4（你的 bot token）
Method：sendMessage
Parameter1：chat_id
Value1：127355800（你的 uid，可以透過 @userinfobot 取得）
Parameter2：text
Value2：Hello,+World!+你好，世界！（空白要用「+」替換）

組合完會像這個樣子，直接貼到瀏覽器的網址列就能使用囉：

1

https://api.telegram.org/bot1985044907:AAEdySrbzTc8tVdBjfymlfyaBUJGeu7r-v4/sendMessage?chat_id=127355800&text=Hello,+World!+你好，世界！

PS：聊天室的 chat_id，先將你的機器人邀請進入聊天室，再使用此網址取得：https://api.telegram.org/bot${your_bot_token}/getUpdates

常見問題：

Token 打錯

1

{"ok":false,"error_code":401,"description":"Unauthorized"}

Method 打錯

1

{"ok":false,"error_code":404,"description":"Not Found"}

chat_id 的值不能為空

1

{"ok":false,"error_code":400,"description":"Bad Request: chat_id is empty"}

chat_id 的值打錯

1

{"ok":false,"error_code":400,"description":"Bad Request: chat not found"}

沒私訊過機器人

1

{"ok":false,"error_code":403,"description":"Forbidden: bot can't initiate conversation with a user"}

text 的值不能為空

1

{"ok":false,"error_code":400,"description":"Bad Request: message text is empty"}

成功的話會返回機器人發送的訊息（json 格式）到網頁上：

1

{"ok":true,"result":{"message_id":5,"from":{"id":1985044907,"is_bot":true,"first_name":"2021 iThome\u9435\u4eba\u8cfd","username":"ironman2021_by_miku3920_bot"},"chat":{"id":127355800,"first_name":"\u521d\u97f3","last_name":"\u30df\u30af","username":"miku3920","type":"private"},"date":1631440402,"text":"Hello, World! \u4f60\u597d\uff0c\u4e16\u754c\uff01"}}

Telegram 機器人的設定

輸入 /mybots 指令後就會出現機器人列表

1

Choose a bot from the list below:

選擇一個你要查看或設定的機器人
我之前就有建立過機器人，所以會顯示兩個

1
2


Here it is: 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot.
What do you want to do with the bot?

點下去後就會出現六個選項，我一個個來講解：

API Token - 查看 token

1
2
3


Here is the token for bot 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot:

1985044907:AAH1kZaEZFHoA6YqB6IFtvbkyOjvcpPOfbQ

忘記 token 時可以來這裡查看，或是你想要重置 token

Revoke current token - 重置 token

1
2
3


Token for the bot 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot has been revoked. New token is:

1985044907:AAG3E05XowN2sqy286aplwr6oBc17q0CByg

按下重置按鈕後，它就會給你一個新的 token，舊的會立即失效

Edit Bot - 修改機器人

1
2
3
4
5
6
7


Edit @ironman2021_by_miku3920_bot info.

Name: 2021 iThome鐵人賽
Description: ?
About: ?
Botpic: ? no botpic
Commands: no commands yet

Edit Name - 修改名字

按下按鈕後會出現以下訊息

1

OK. Send me the new name for your bot.

直接傳送新的名稱給它就行了

1

Success! Name updated. /help

看到這個就是修改成功了

Edit Description - 修改說明

這個會顯示在聊天室的最上方，用來說明機器人有能些功能，或是如何使用

1

OK. Send me the new description for the bot. People will see this description when they open a chat with your bot, in a block titled 'What can this bot do?'.

傳送一段訊息給它，可以是多行的文字

1

Success! Description updated. /help

看到這個就是修改成功了

原本在聊天室上方啥都沒有，現在多了一個訊息框

Edit About - 修改簡介

這個會顯示在機器人的個人資訊頁面上

1

OK. Send me the new 'About' text. People will see this text on the bot's profile page and it will be sent together with a link to your bot when they share it with someone.

傳送一段訊息給它，可以是多行的文字

1

Success! About section updated. /help

看到這個就是修改成功了

原本是只有顯示 username，現在多了簡介

Edit Botpic - 修改大頭貼

1

OK. Send me the new profile photo for the bot.

建議先裁切成正方形（1：1）

1

Please send me the picture as a 'Photo', not as a 'File'.

這邊要傳送照片，不能傳檔案

1

Success! Profile photo updated. /help

成功的話，機器人的大頭貼就會更新成剛剛上傳的圖片

Edit Commands - 修改指令選單

1
2
3
4
5
6


OK. Send me a list of commands for your bot. Please use this format:

command1 - Description
command2 - Another description

Send /empty to keep the list empty.

要按照它給的格式輸入，不需要打 /

1

Success! Command list updated. /help

成功的話，選單中就會出現剛剛設定的指令

如果機器人是在群組使用，建議改成空的，避免誤觸
群組裡較常使用 ! 開頭的指令，這樣才不會變成藍藍的容易按到
在剛剛那邊，按 /empty 就行了

修改完會變成這樣：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Edit @ironman2021_by_miku3920_bot info.

Name: 2021 iThome鐵人賽
Description: 一些說明文字，功能如下：

1. AAA
2. BBB
3. CCC
About: 鐵人賽展示用機器人 by @miku3920
鐵人賽展示用機器人 by @miku3920
鐵人賽展示用機器人 by @miku3920
Botpic: ? has a botpic
Commands: no commands yet

Bot Settings - 設定機器人

1

Settings for @ironman2021_by_miku3920_bot.

Inline Mode - 內聯模式（內嵌模式）

可以讓機器人直接在訊息輸入框使用，不需要將機器人加入群組
這個功能夠講一整天了，目前還用不到，我們以後專門找一天來講

Allow Group? - 是否能被加入群組?

1
2
3


Groups are currently enabled for bot 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot

Disabling groups will forbid users to add 2021 iThome鐵人賽 to groups.

enabled(預設) - 表示機器人能被別人拉進群組
如果你不想讓別人拉你的機器人，可以按 Turn groups off

1
2
3


Groups are currently disabled for bot 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot.

Enabling groups will allow users to add 2021 iThome鐵人賽 to groups.

disabled - 表示機器人不能被別人拉進群組
如果你想讓別人的群組也能使用你的機器人，就按 Turn groups on

Group Privacy - 是否能讀取所有聊天室訊息

官方說明

1

Privacy mode is enabled for 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot.

enabled(預設) - 表示機器人是成員時不能讀取群組裡的所有訊息

機器人只看的到它的指令和回覆它的訊息

但是如果升級成管理員就沒這限制

1

Privacy mode is disabled for 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot.

disabled - 表示機器人就算不是管理員也能讀取群組裡的所有訊息

機器人是成員時就能讀取所有訊息

Payments - 付款相關設定

台灣不能用，有生之年系列，跳過

Domain - 網站登入用

與機器人較無關，暫時不提

Payments - 付款相關設定

歐付寶、綠界、台灣 pay、街口、悠遊付，不考慮進駐一下嗎

Transfer Ownership - 轉移機器人

⚠️ 注意：非必要請勿使用！

Choose recipient - 選擇使用者

1

Please share the new owner's contact or their username.

按下按鈕後，它會請你把對方以聯絡人的方式分享給它，或是輸入對方的 username

常見問題：

要輸入 @username，不能只輸入 username

1

Incorrect format. Please make sure to send either a contact or username.

不能轉移給頻道、機器人、或是自己

1

Bot ownership can't be transferred to channel, another bot or yourself.

對方要私訊過機器人，而且不能封鎖機器人

1

Oops! Please make sure the new owner has sent at least one message to the bot and didn't block it.

輸入正確的話，就會出現以下訊息：

1
2
3
4
5


You are about to transfer ownership of the bot @ironman2021_by_miku3920_bot to 初音 ミク.

After this you won't be able to control the bot anymore. The new owner will get access to the bot messages and other data – and can even delete the bot completely.

Please make sure you don't violate your users' privacy (consider GDPR and other laws). If you are sure please press the button below.

看到這則訊息代表離成功轉移不遠了

Yes, I am sure, proceed. - 確認轉移

如果你有設定兩步驟驗證的話，這邊會跳出來要你輸入

常見問題：

對方擁有的機器人數量已達上限

1

Oops! has reached the maximum allowed number of bots. Please ask them to delete (or pass to another account) one of their unused bots first.

如果對方已經有 20 隻機器人（達到上限），就會出現這個對話框，他請你先叫對方轉移或刪除一些沒在用的機器人，這樣你才可以轉移給對方。

1

It worked! We hope @ironman2021_by_miku3920_bot will enjoy its new home.

如果轉移成功就會出現這則訊息

1
2
3


Ownership of the bot @ironman2021_by_miku3920_bot has been transferred to you by 初音 ミク. You can now control the bot using /mybots.

If you did not request this, you can delete the bot.

Delete Bot - 刪除機器人

⚠️ 注意：非必要請勿使用！

1

You are about to delete your bot 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot. Is that correct?

這邊的按鈕順序是隨機的，避免你頭腦不清楚把機器人刪了

1

Are you TOTALLY sure you want to delete 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot ?

要連續按兩次 Yes 機器人才會被刪掉

1

You have deleted 2021 iThome鐵人賽 @ironman2021_by_miku3920_bot.

看到這則訊息表示機器人已經刪除，無法復原
所有群組裡的這隻機器人都會顯示成 Deleted Account

Bonus：Drone CI/CD 流程失敗時，叫你的 Telegram 機器人通知你！

建立群組，並取得群組的 chat_id

Telegram 建立群組，並將你的 Telegram 機器人拉進群組內(@{your bot username})。
透過此 API 取得群組的 chat_id：

1

https://api.telegram.org/bot${your bot token}/getUpdates

getUpdates API 會取得 json，找到你剛剛開的群組的 chat_id

透過 Drone Plugin

從 Drone Plugin 可以找到很多套件，可以搭配 CI/CD 使用，而我從這找到 Telegram by appleboy 的套件。

Drone CI/CD 補上告警的 step。

你的 Drone CI/CD step 加上使用 Telegram by appleboy 叫你的機器人於 pipeline 失敗時於群組內發出告警。

PS：記得將你的 telegram bot token 與群組的 chat_id 加到 Drone Secrets。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


kind: pipeline
type: docker
name: install and deploy
steps:
 - name: build
 image: node:15
 commands:
 - node --version
 - yarn --version
 # - yarn cache clean -f
 - yarn install --ignore-engines
 - yarn run build
 - ls -al dist/static/
 when:
 branch:
 - master
 event:
 - push

 - name: deploy
 image: thegeeklab/drone-s3-sync
 settings:
 bucket: xxxxxxxxx(你的aws s3 bucket)
 access_key:
 from_secret: aws_access_key_id
 secret_key:
 from_secret: aws_secret_access_key
 source: ./dist/
 target: /admin
 acl:
 "*": public-read
 region: xxxxxxxxx(你的aws s3 region)
 delete: true
 cloudfront_distribution: xxxxxxxxx(你的aws cloudfront distribution)
 when:
 branch:
 - master
 event:
 - push

+ - name: send telegram notification
+ image: appleboy/drone-telegram
+ settings:
+ token:
+ from_secret: telegram_bot_token
+ to:
+ from_secret: telegram_chat_id
+ format: markdown
+ message: >
+ `{{repo.name}}` 於 `{{commit.branch}}` 編譯失敗：#`{{build.number}}`
+ when:
+ status: [failure]

token：你的 Telegram 機器人的 token。
to： chat_id。
format：使用 markdown 格式。
message：機器人傳的訊息。
when.status [failure]：當此 pipeline 失敗時觸發此 step(send telegram notification)，亦可於成功或失敗皆告警：[success, failure]。

詳細參數可參考 Drone Plugin - appleboy/drone-telegram

Telegram Bot on Wayne's blog | 偉恩的部落格 | 技術博客

Telegram 機器人說明，並為你的 Drone CI/CD 配置 Telegram 機器人

Telegram 聊天機器人原理

機器人的運作原理

機器人接收訊息的兩種模式

機器人發送訊息的三種方式

向 @BotFather 申請一隻機器人吧！

The BotFather

@BotFather 的功能

建立你的機器人吧

使用你的機器人吧

Telegram 機器人的設定

API Token - 查看 token

Edit Bot - 修改機器人

Edit Name - 修改名字

Edit Description - 修改說明

Edit About - 修改簡介

Edit Botpic - 修改大頭貼

Edit Commands - 修改指令選單

Bot Settings - 設定機器人

Inline Mode - 內聯模式（內嵌模式）

Allow Group? - 是否能被加入群組?

Group Privacy - 是否能讀取所有聊天室訊息

Payments - 付款相關設定

Domain - 網站登入用

Payments - 付款相關設定

Transfer Ownership - 轉移機器人

Choose recipient - 選擇使用者

Yes, I am sure, proceed. - 確認轉移

Delete Bot - 刪除機器人

Bonus：Drone CI/CD 流程失敗時，叫你的 Telegram 機器人通知你！

建立群組，並取得群組的 chat_id

透過 Drone Plugin

Drone CI/CD 補上告警的 step。

向 `@BotFather` 申請一隻機器人吧！