# Bots: An introduction for developers(翻譯)
###### tags: `telegram` `bot`
:::danger
[官方文件](https://core.telegram.org/bots#6-botfather)
:::

[TOC]

Bots是應用於Telegram的第三方應用程式。使用者可以透過傳遞訊息、命令以及[inline requests](https://core.telegram.org/bots#inline-mode)來與bots互動。你可以用HTTPS requests到我們的bot API來控制你的bots。

## 1. What can I do with bots?
幾是舉幾個例子，你可以用bots做：
* **取得自定義的通知與新聞**。機器人可以做為智能報紙，在發佈之後立即向你發送相關內容。
* **與其它服務整合**。bot可以利用外部服務的內容來豐富Telegram的聊天。[Gmail Bot](https://t.me/gmailbot)，[Image Bot](https://t.me/imagebot)，[GIF bot](https://t.me/gif)，[IMDB bot](https://t.me/imdb)，[Wiki bot](https://t.me/wiki)，[Music bot](https://t.me/music)，[Youtube bot](https://t.me/youtube)，[GitHub bot](https://t.me/githubbot)。
* **接受Telegram使用者的付款**。bot可以提供付費服務或做為虛擬店面。[更多](https://core.telegram.org/bots/payments)。[Demo Shop Bot](https://t.me/shopbot)。
* **建立客製化工具**。bot也許可以提供你警報、天氣預測、翻譯、格式化或其它服務。[Markdown bot](https://t.me/Bold)，[Sticker bot](https://t.me/sticker)，[Vote bot](https://t.me/vote)，[Like bot](https://t.me/like)。
* **建立單人或多人遊戲**。bot可以提供豐富的[HTML5](https://core.telegram.org/bots/games)的體驗，從簡單的街機遊戲、拼圖到3D射擊遊戲與即時戰略遊戲。[GameBot](https://t.me/gamebot)，[Gamee](https://t.me/gamee)。
* **建立社群服務**。bot可以根據共同的興趣或接近程度來將尋找對話夥伴的人連接起來。[HotOrBot](https://t.me/hotorbot)
* **幾乎可以做其它任何事情**。除了洗碗-bots洗碗的時候非常糟糕。

## 2. How do bots work?
本質上，Telegram Bots是特殊帳戶，並不需要設置額外的電話號碼。使用者可以以兩種方式與bots互動：
* 透過開啟一個與bots的聊天或增加它們到群組的方式來發送訊息與命令。這對chat bots或news bots(如官方TechCrunch bot)非常有用。
* 透過輸入bot的`@username`與查詢，直接從輸入字段發送請求。這允許將inline bots的內容直接發送到任何聊天、群組或頻道。

使用者發送的訊息、命令與請求傳到你的伺服器上執行的軟體。我們的中介服務可以替你處理與Telegram API進行的所有加密與通信。你通過一個簡單的HTTPS介面與這伺服器進行通信，這介面提供簡化的Telegram API版本。我們將這介面稱為Bot API。

>更細部的Bot API說明提供於此[頁面>>](https://core.telegram.org/bots/api)

## 3. How do I create a bot?
有一個bot專門處理這個。只要與[BotFather](https://core.telegram.org/bots/api)(下面說明)交談，並跟著一些簡單的步驟就可以。在你建立bot並收到你的授權token之後，直接到[Bot API手冊](https://core.telegram.org/bots/api)看看你可以教你的bot做些什麼。

>你還可以在這邊看一些[範例程式碼>>](https://core.telegram.org/bots/samples)

## 4. How are bots different from humans?
* Bots沒有在線狀態，也沒有上次出現時間，而界面會顯示標籤"bot"。
* Bots的雲端儲存空間有限-舊的訊息可能在處理之後的不久就被伺服器刪除。
* Bots無法發起與用戶的對話。用戶必須將它們加入群組或先向他們發送訊息。人們可以使用`t.me/<bot_username>`連結或使用者搜尋來找到你的bot。
* Bot的使用者名稱總是以"bot"結尾(像是[@TriviaBot](Bots)，[@GitHub_bot](https://t.me/githubbot))。
* 當bot被加到群組的時候，預設情況下，bots並不會接收所有的訊息(見[隱私模式](https://core.telegram.org/bots#privacy-mode))。
* Bots永遠不會吃、睡與抱怨(除非另外有明確的寫程式)。

## 5. Bot perks
Telegram bots在很多方面都是獨一無二的-我們提供兩種鍵盤，用於預設命令的附加介面，深度連接[文本的格式](https://core.telegram.org/bots/api#formatting-options)，等等。

### Inline mode
使用者可以在任何的聊天中的文本輸入字段中透過[inline queries](https://core.telegram.org/bots/api#inline-mode)與你的bot互動。他們所需要做的就只是用你bot的使用者名稱來開始一則訊息，然後輸入一個查詢。

收到查詢之後，你的bot會回傳一些結果。只要使用者點擊其中一則，它就會發送到使用者當前開啟的聊天中。這樣，人們就可以在任何的聊天、群組或頻道中向你的bot請求內容。

查詢這篇[blog](https://telegram.org/blog/inline-bots)，看看執行中的inline bot範例。你也可以嘗試[@sticker](https://t.me/sticker)與[@music](https://t.me/music)兩個bots來體驗一下。

我們還為你的bot實作一種簡單的方法，讓你的bot可以在[inline與PM模式中切換](https://core.telegram.org/bots/inline#switching-inline-pm-modes)。

>[更多關於Inline Model](https://core.telegram.org/bots/inline)

### Payments platform
你可以使用bots接受來自世界各地的Telegram使用者的付款。

從使用者角度來看，系統是無縫整合的。你的bot發送一個特別格式的**invoice message**。這類訊息帶有照片與產品說明以及醒目的**付款**按鈕。點擊這個按鈕，在Telegram應用程式中開啟一個特殊的付款介面。

使用者輸入必要的資訊，選擇一張已保存的信用卡或輸入新的(Telegram也支援Apple Pay與Android Pay)-然後為你的產品付款。流程如下所示：
[影片連結](https://core.telegram.org/file/811140436/2/cxE7JK8NL-M.514213.mp4/2146f9b746ebb4fef4)

>[更多關於付款平台資訊>>](https://core.telegram.org/bots/payments)
### Gaming platform
Bots可以提供使用者**HTML5的遊戲**，讓他們可以單獨玩或在群組與一對一聊天中互相競爭。這個平台允許你的bot追蹤每次聊天中玩的每個遊戲的**高分**。每當有遊戲中有新的最高分人員出現，聊天中的其他玩家都會收到通知，他們需要加強。


由於底層的技術是HTML5，因此遊戲可以是任何遊戲，從簡單的街機、拼圖到多人3D射擊與即時戰略遊戲。我們的團隊建立一些簡單的範例供你測試：
* [Math Battle](https://t.me/gamebot?game=MathBattle)
* [Lumberjack](https://t.me/gamebot?game=Lumberjack)
* [Corsairs](https://t.me/gamebot?game=Corsairs)

你還可以查看擁有超過20款遊戲的[@gamee](https://t.me/gamee)

>[更多關於遊戲平台資訊>>](https://telegram.org/blog/games)

### Keyboards
當然可以教傳統的chat bots理解人類語言。但有時候你需要使用者提供更正式的輸入-這就是自定義鍵盤變的非常有用的地方。

每當你的bot發送一則訊息的時候，它就可以通過一個帶有預定義回覆選項的特殊鍵盤來回覆(見[ReplyKeyboardMarkup](https://core.telegram.org/bots/api/#replykeyboardmarkup))。接收到訊息的Telegram應用程式將會向使用者顯示你定義的鍵盤。點擊任一按鈕將立節發送相對應命令。這樣，你就可以大大簡化使用者與bot的互動。

我們目前支援文字與表情符號按鈕。這邊是一些自定義鍵盤的範例：

>更多自定義鍵盤的技術資訊，請參考[Bot API manual](https://core.telegram.org/bots/api)(見[sendMessage](https://core.telegram.org/bots/api#sendmessage))

### Inline keyboards and on-the-fly updating
有些時候，你寧願在不向聊天室發送任何訊息的情況下執行操作。舉例來說，當你的使用者改變設置或瀏灠搜尋結果的時候。這種情況下，你可以使用直接集成到所有訊息中的Inline Keyboards。

不同於自定義的reply keboards，在inline keyboards按按鈕並不會導致訊息發送到聊天室。相反的，inline keyboards支援背景工作的按鈕：[callback buttons](https://core.telegram.org/bots/2-0-intro#callback-buttons)，[URL buttons](https://core.telegram.org/bots/2-0-intro#url-buttons)與[switch to inline buttons](https://core.telegram.org/bots/2-0-intro#switch-to-inline-buttons)。


當使用callback buttons時，你的bot可以更新其現有的訊息，以便讓聊天室保持整潔。查看這些範例bots，以查看inline keyboard的執行狀況：[@music](https://t.me/music)，[@vote](https://t.me/vote)，[@like](https://t.me/like)。

>[更多關於inline keyboard與on-the-fly editing>>](https://core.telegram.org/bots/2-0-intro#new-inline-keyboards)
### Commands
命令提供一種與你的bot溝通更靈活的方法。可以使用下面語法：

/command

命令必須以'/'符號開頭，而且不能超過32個字符。命令可以使用拉丁字母，數字與底線。這邊有一些範例：

/get_messages_stats
/set_timer 10min Alarm!
/get_timezone London, UK

以'/'開頭的訊息總是傳遞給bot(以及對訊息的回覆，以及@依使用者提供bot的訊息)。Telegram應用程式將：
* 當使用者輸入'/'的時候，建議帶有[supported commands](https://core.telegram.org/bots#edit-settings)的清單(要讓它正常運作，你需要向BotFather提供命令清單)。點擊清單中的命令會立即發送命令。
* 在與bot進行所有聊天中的輸入字段中顯示一個附加(/)按鈕。點擊它會寫入一個'/'並顯示命令清單。
* 突顯出訊息中的`/command`。當使用者點擊突顯出的命令時，該命令會立即發送。

如果群組中有多個bots，那就可以在命令中加入bot使用者名稱以避免混淆：

/start@TriviaBot
/start@ApocalypseBot

當通過建立的命令清單選擇之後，將自動完成這個操作。請記得，你的bot需要能夠處理後面跟著其使用者名稱的命令。
### Global commands
為了讓用戶更方便瀏灠bot的多元世界，我們要求所有開發人員支援一些基本命令。Telegram應用程式將具有這些命令的介面快捷方式。
* /start - 透過發送問候訊息開始與用戶互動。這個命令還可以用來將其它參數傳遞給bot(見Deep linking)
* /help - 回傳說明訊息。可以是關於你的bot可以做什麼的簡短文本以及命令清單。
* /settings - (如果適用)回傳該用戶的bot設置，並建議用於編輯這些設置的命令。

當用戶第一次開啟與你的bot的對話時，他們將看到一個`Start`按鈕。說明與設置連結將在bot的資料頁面上的功能表提供。


### Formatting: bold, italic, fixed-width text and inline links
你可以在你bot的訊息中使用粗體，斜體或固定寬度文本，以及inline link。Telegram客戶端將相對應的呈現它們。

>[Read more in the Bot API manual »](https://core.telegram.org/bots/api#formatting-options)
### Privacy mode
Bots經常被加入群組，以增強人類用戶之間的通信，例如，透過提供新聞，來自外部的服務或其它搜尋功能。與工作相關的群組尤其如此。現在，當你與bot分享一個群組的時候，你往往會問自己："我怎麼能確定這個搗蛋鬼不會把我的聊天記錄賣給我的競爭對手?"答案是-隱私模式。

隱私模式下執行的bot不會收到人們發送到群組的所有訊息。相反的，它將只收到：
* 以斜線`/`起始的訊息(見上面Commands)
* 回覆bot自己的訊息
* 服務訊息(從群組增加或刪除的人)
* 來自其成員的頻道訊息

一方面，這有助於我們當中的一些人晚上睡的更好(在我們的錫箔睡帽裡)，另一方面-它允許bot開發人員節省大量資源，因為他們不需要每天處理成千上萬無關的訊息。

所有bots預設啟用隱私模式，但以管理員身份加到群組中的bot除外(bot管理員永遠收到所有訊息)。它是可以關閉的，以便bot可以像是普通用戶一樣接收所有訊息(bot需要重新加到群組中，以便生效變更)。我們只建議在你的bot在工作上絕對需要的時候執行這麼做-用戶始終可以在群組成員清單中看到bot的當前隱私設置。更多情況下，使用對bot的訊息使用選項[force reply](https://core.telegram.org/bots/api#forcereply)應該已經足夠。

[So what messages exactly will my bot get? »](https://core.telegram.org/bots/faq#what-messages-will-my-bot-get)
### Deep linking
Telegram bots有一個[deep linking](https://en.wikipedia.org/wiki/Deep_linking)機制,該機制允許在啟動的時候傳遞其它參數給bot。可能是啟動bot的命令-或者是一個連結用戶的Telegram帳戶到外部服務上的帳戶的的授權token。

每一個bot都有一個連結，在Telegram中開啟一個對話-`https://t.me/<bot username>`。你可以將參數`start`或`startgroup`加到這個連結，最長64個字符。舉例來說：

https://t.me/triviabot?startgroup=test

`A-Z`, `a-z`, `0-9`, `_` 與 `-` 都是允許的。我們建議使用[base64url](https://en.wikipedia.org/wiki/Base64#URL_applications)做為編碼帶有二進制與其它類型內容的參數

使用參數`start`連接後，將打開與bot的一對一對話，在輸入字段的位置中顯示一個start按鈕。如果使用參數`startgroup`，那就提示用戶選擇一個群組來將bot加入。一旦用戶確認操作()，你的bot將收到來自該用戶此格式的訊息：

/start PAYLOAD

`PAYLOAD`代表連結中傳遞的參數`start`或`startgroup`的值。
### Deep linking Example
假設網路example.com想通過Telegram bot向它的用戶發送通知。下面是他們可以為ID`123`的用戶啟用通知的方法。

1. 使用適當的使用者名稱建立bot，像是，@ExampleComBot
2. 為進入的訊息設置[webhook](https://core.telegram.org/bots/api#setwebhook)
3. 生成一個有效長度的隨機字串，像是，`$memcache_key = "vCH1vGWJxfSeofSAs0K5PA"`
4. 將帶鑰匙`$memcache_key`的值`123`放入Memcache(3600秒，一小時)
5. 向用戶顯示按鈕
6. 配置webhook處理器以處理`/start`開頭的傳入訊息中傳遞的參數查詢Memcached。如果金鑰存在，那就記錄傳遞給webhook的chat_id作為使用者 `123`的**telegram_chat_id**。從Memcache刪除金鑰。
7. 現在，當我們想要發送通知給用戶`123`的時候，檢查他們是否擁有字段**telegram_chat_id**。如果擁有，那就在[Bot API](https://core.telegram.org/bots/api)中使用方法[sendMessage](https://core.telegram.org/bots/api#sendmessage)在Telegram中向他們發送訊息。

### Location and Number
有些bot需要用戶提供額外的資料才能正常的工作。舉例來說，瞭解用戶位置有助於提供更多相關地理特定結果。用戶電話號碼對整合其它服務(像是銀行)非常有用。

bots可以使用特殊按鈕詢問用戶的位置與電話號碼。注意到，電話號碼與位置的請求按鈕都只能在私密聊天中使用。


當這些按鈕被按下的時候，Telegram客戶端將顯示確認警報，並告知用戶將要發生的情況。

>[手冊: Number and location buttons »](https://core.telegram.org/bots/api#keyboardbutton)

## 6. BotFather
[BotFather](https://t.me/botfather)是統治所有機器人的機器人。它將幫助你建立新的bots與對已存在的bots改變設置。

### Creating a new bot
使用命令`/newbot`建立新的bot。BotFather將會問你名稱(name)與使用者名稱(username)，然後生成一個授權token給你的新bot。

你的bot的名稱(name)顯示在聯絡人清單與其它地方。

使用者名稱(Username)是一個簡稱。用於提及與`t.me`連接。使用者名稱為5-32字符長，不區分大小寫，但是只包含拉丁字符，數值與底線。你的bot的使用者名稱必須以'bot'結尾，例如，'tetris_bot'或'TetrisBot'

token是一個字串，類似於`110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw`，這是授權bot並發送請求到[Bot API](https://core.telegram.org/bots/api)所需要的。確保你的token保密並安全的保存，任何人都可以用它來控制你的bot。

### Generating an authorization token
如果你的已存在token因為某些原因被盜或遺失，使用命令`/token`來生成一個新的。

### Botfather commands
其它的命令很簡單：
* /mybots — 回傳帶有方便控制的bots清單，以編輯bots的設置。
* /mygames — does the same for your games
#### Edit bots
* /setname – 修正你的bot的名稱(name)
* /setdescription — 修正bot的描述，簡短的文字，最多512個字符，描述你的bot。使用者將會在與bot互動的時候看見這個文本，標題為'What can this bot do?'。
* /setabouttext — 修正bot的關於信息，甚至是更短的文字，最多120個字符。使用者將在bot的資料頁面中看到這些文本。當他們分享你的bot給某些人的時候，這文本會連同連結一同發送。
* /setuserpic — 修正bot的資料照片。將照片放名字上總是好的。
* /setcommands — 修正你的bot支援的命令清單。使用者將會在與你的bot的聊天中輸入`/`的時候看到這些命令。每一個命令都有一個名稱(必須起始於斜線`/`，字母數字加上底線，不能超過32個字符，不分大小寫)，參數，以及說明。使用者在與你的bot對話中輸入'/'將會看到命令清單。
* /deletebot — 刪除你的bot並釋放它的使用者名稱(username)。

#### Edit settings
* /setinline — 切換你的bot為inline mode。
* /setinlinegeo - 請求位置資料來提供[基於位置](https://core.telegram.org/bots/inline#location-based-results)的inline結果。
* /setjoingroups — 切換是否可以將你的bot加入群組內。任何的bot都必須能夠處理私人訊息，但是如果你的bot並不是設計來在群組內工作的，你可以關閉這個。
* /setprivacy — 設置當你的bot被加入群組的時候會收到的訊息。當隱私模式被關閉的時候，bot將會將到所有的訊息。我們建立保留啟用[隱私模式](https://core.telegram.org/bots#privacy-mode)。你將需要重新加入bot到已存在的群組，這個改變才會生效。

#### Manage games
* /newgame — 建立新的[遊戲](https://core.telegram.org/bots/games)。
* /listgames — 取得你的遊戲清單。
* /editgame — 編輯遊戲。
* /deletegame — 刪除一個已存在的遊戲。

>請注意，可能需要等待幾分鐘讓修改生效。

### Status alerts
數以百萬的人們選擇Telegram是因為它的速度。要在這環境中保留競爭力，你的bot還需要響應。為了幫開發人員保留他們bots的形狀，Botfather將在bot看起來發生錯誤的時候發送狀態警報。

我們將檢查受歡迎的bots的回覆數的請求/響應轉換率(每分鐘約300個請求，但不要寫下來，因為這個值將來可能會改變)。如果我們得到異常低的讀數，你將會收到Botfather的通知。
### Responding to alerts
預設情況下，每個bot每小時只會收到一個警報。每個警報會有下列按鈕：
* Fixed-如果你發現你的bot有問題並已修復它，使用這個按鈕。如果你按下修復按鈕，我們將繼續以常規方法發送警報，以便可以確認你的修復是否在5-10分內生效，而不必等待一小時。
* Support-如果你看不出你的bot有任何問題，或者你認為問題在我們這邊，請使用這個按鈕開發與@BotSuport的對話。
* Mute for 8h/1w-如果你現在不能修好你的bot，使用這個按鈕。這將在指定時間段內禁用有問題的bot的所有警報。我們不建議使用這個選項，因為你的使用者可能會遷移到更穩定的bot。你可以透過Botfather在你的bot設置中取消警報的靜音。

### Monitored issues
我們目前將通知你以下問題：
1.

Too few **private messages** are sent compared to previous weeks: **{value}**

你的bot發送的訊息前前幾週要少的多。這對不需要用戶提示就發送訊息的通訊樣式的bot非常有用。值愈大，差異愈顯著。

2.

Too few replies to incoming **private messages**. Conversion rate: **{value}**

你的bot沒有回應發給它的所有訊息(在過去三個五分鐘內的至少兩個，其bot的請求/響求轉換率太低)。為了提供好的用戶體驗，請回覆發送到你的bot的所有訊息。通過呼叫send...方法來響應消息更新。(例如`sendMessage`)

3.

Too few answers to **inline queries**. Conversion rate: **{value}**

你的bot沒有回覆發送給它的所有inline queries，計算方法與上面相同。透過呼叫`answerInlineQuery`響應inline_query更新。

4.

Too few answers to **callback queries**. Conversion rate: **{value}**
Too few answers to **callback game queries**. Conversion rate: **{value}**

你的bot不會回覆所有發送給它的callback queries(有或沒有遊戲)，計算與上面相同。透過呼叫`answerCallbackQuery`響應callback_query更新。

>請注意，狀態警報功能仍然在測試中，未來還會改進。

這是介紹，你現在已經準備好去[BOT API MANUAL](https://core.telegram.org/bots/api).

如果你有任何問題，請查閱我們的[Bot FAQ »](https://core.telegram.org/bots/faq)