Bots: An introduction for developers(翻譯)
Bots是應用於Telegram的第三方應用程式。使用者可以透過傳遞訊息、命令以及inline requests來與bots互動。你可以用HTTPS requests到我們的bot API來控制你的bots。
1. What can I do with bots?
幾是舉幾個例子，你可以用bots做：
- 取得自定義的通知與新聞。機器人可以做為智能報紙，在發佈之後立即向你發送相關內容。
- 與其它服務整合。bot可以利用外部服務的內容來豐富Telegram的聊天。Gmail Bot，Image Bot，GIF bot，IMDB bot，Wiki bot，Music bot，Youtube bot，GitHub bot。
- 接受Telegram使用者的付款。bot可以提供付費服務或做為虛擬店面。更多。Demo Shop Bot。
- 建立客製化工具。bot也許可以提供你警報、天氣預測、翻譯、格式化或其它服務。Markdown bot，Sticker bot，Vote bot，Like bot。
- 建立單人或多人遊戲。bot可以提供豐富的HTML5的體驗，從簡單的街機遊戲、拼圖到3D射擊遊戲與即時戰略遊戲。GameBot，Gamee。
- 建立社群服務。bot可以根據共同的興趣或接近程度來將尋找對話夥伴的人連接起來。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說明提供於此頁面>>
3. How do I create a bot?
有一個bot專門處理這個。只要與BotFather(下面說明)交談，並跟著一些簡單的步驟就可以。在你建立bot並收到你的授權token之後，直接到Bot API手冊看看你可以教你的bot做些什麼。
你還可以在這邊看一些範例程式碼>>
4. How are bots different from humans?
- Bots沒有在線狀態，也沒有上次出現時間，而界面會顯示標籤"bot"。
- Bots的雲端儲存空間有限-舊的訊息可能在處理之後的不久就被伺服器刪除。
- Bots無法發起與用戶的對話。用戶必須將它們加入群組或先向他們發送訊息。人們可以使用
t.me/<bot_username>連結或使用者搜尋來找到你的bot。 - Bot的使用者名稱總是以"bot"結尾(像是@TriviaBot，@GitHub_bot)。
- 當bot被加到群組的時候，預設情況下，bots並不會接收所有的訊息(見隱私模式)。
- Bots永遠不會吃、睡與抱怨(除非另外有明確的寫程式)。
5. Bot perks
Telegram bots在很多方面都是獨一無二的-我們提供兩種鍵盤，用於預設命令的附加介面，深度連接文本的格式，等等。
Inline mode
使用者可以在任何的聊天中的文本輸入字段中透過inline queries與你的bot互動。他們所需要做的就只是用你bot的使用者名稱來開始一則訊息，然後輸入一個查詢。
收到查詢之後，你的bot會回傳一些結果。只要使用者點擊其中一則，它就會發送到使用者當前開啟的聊天中。這樣，人們就可以在任何的聊天、群組或頻道中向你的bot請求內容。
查詢這篇blog，看看執行中的inline bot範例。你也可以嘗試@sticker與@music兩個bots來體驗一下。
我們還為你的bot實作一種簡單的方法，讓你的bot可以在inline與PM模式中切換。
Payments platform
你可以使用bots接受來自世界各地的Telegram使用者的付款。
從使用者角度來看，系統是無縫整合的。你的bot發送一個特別格式的invoice message。這類訊息帶有照片與產品說明以及醒目的付款按鈕。點擊這個按鈕，在Telegram應用程式中開啟一個特殊的付款介面。
使用者輸入必要的資訊，選擇一張已保存的信用卡或輸入新的(Telegram也支援Apple Pay與Android Pay)-然後為你的產品付款。流程如下所示：
影片連結
Gaming platform
Bots可以提供使用者HTML5的遊戲，讓他們可以單獨玩或在群組與一對一聊天中互相競爭。這個平台允許你的bot追蹤每次聊天中玩的每個遊戲的高分。每當有遊戲中有新的最高分人員出現，聊天中的其他玩家都會收到通知，他們需要加強。
由於底層的技術是HTML5，因此遊戲可以是任何遊戲，從簡單的街機、拼圖到多人3D射擊與即時戰略遊戲。我們的團隊建立一些簡單的範例供你測試：
你還可以查看擁有超過20款遊戲的@gamee
Keyboards
當然可以教傳統的chat bots理解人類語言。但有時候你需要使用者提供更正式的輸入-這就是自定義鍵盤變的非常有用的地方。
每當你的bot發送一則訊息的時候，它就可以通過一個帶有預定義回覆選項的特殊鍵盤來回覆(見ReplyKeyboardMarkup)。接收到訊息的Telegram應用程式將會向使用者顯示你定義的鍵盤。點擊任一按鈕將立節發送相對應命令。這樣，你就可以大大簡化使用者與bot的互動。
我們目前支援文字與表情符號按鈕。這邊是一些自定義鍵盤的範例：
更多自定義鍵盤的技術資訊，請參考Bot API manual(見sendMessage)
Inline keyboards and on-the-fly updating
有些時候，你寧願在不向聊天室發送任何訊息的情況下執行操作。舉例來說，當你的使用者改變設置或瀏灠搜尋結果的時候。這種情況下，你可以使用直接集成到所有訊息中的Inline Keyboards。
不同於自定義的reply keboards，在inline keyboards按按鈕並不會導致訊息發送到聊天室。相反的，inline keyboards支援背景工作的按鈕：callback buttons，URL buttons與switch to inline buttons。
當使用callback buttons時，你的bot可以更新其現有的訊息，以便讓聊天室保持整潔。查看這些範例bots，以查看inline keyboard的執行狀況：@music，@vote，@like。
Commands
命令提供一種與你的bot溝通更靈活的方法。可以使用下面語法：
/command
命令必須以’/'符號開頭，而且不能超過32個字符。命令可以使用拉丁字母，數字與底線。這邊有一些範例：
/get_messages_stats
/set_timer 10min Alarm!
/get_timezone London, UK
以’/'開頭的訊息總是傳遞給bot(以及對訊息的回覆，以及@依使用者提供bot的訊息)。Telegram應用程式將：
- 當使用者輸入’/'的時候，建議帶有supported commands的清單(要讓它正常運作，你需要向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客戶端將相對應的呈現它們。
Privacy mode
Bots經常被加入群組，以增強人類用戶之間的通信，例如，透過提供新聞，來自外部的服務或其它搜尋功能。與工作相關的群組尤其如此。現在，當你與bot分享一個群組的時候，你往往會問自己："我怎麼能確定這個搗蛋鬼不會把我的聊天記錄賣給我的競爭對手?"答案是-隱私模式。
隱私模式下執行的bot不會收到人們發送到群組的所有訊息。相反的，它將只收到：
- 以斜線
/起始的訊息(見上面Commands) - 回覆bot自己的訊息
- 服務訊息(從群組增加或刪除的人)
- 來自其成員的頻道訊息
一方面，這有助於我們當中的一些人晚上睡的更好(在我們的錫箔睡帽裡)，另一方面-它允許bot開發人員節省大量資源，因為他們不需要每天處理成千上萬無關的訊息。
所有bots預設啟用隱私模式，但以管理員身份加到群組中的bot除外(bot管理員永遠收到所有訊息)。它是可以關閉的，以便bot可以像是普通用戶一樣接收所有訊息(bot需要重新加到群組中，以便生效變更)。我們只建議在你的bot在工作上絕對需要的時候執行這麼做-用戶始終可以在群組成員清單中看到bot的當前隱私設置。更多情況下，使用對bot的訊息使用選項force reply應該已經足夠。
So what messages exactly will my bot get? »
Deep linking
Telegram bots有一個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做為編碼帶有二進制與其它類型內容的參數
使用參數start連接後，將打開與bot的一對一對話，在輸入字段的位置中顯示一個start按鈕。如果使用參數startgroup，那就提示用戶選擇一個群組來將bot加入。一旦用戶確認操作()，你的bot將收到來自該用戶此格式的訊息：
/start PAYLOAD
PAYLOAD代表連結中傳遞的參數start或startgroup的值。
Deep linking Example
假設網路example.com想通過Telegram bot向它的用戶發送通知。下面是他們可以為ID123的用戶啟用通知的方法。
- 使用適當的使用者名稱建立bot，像是，@ExampleComBot
- 為進入的訊息設置webhook
- 生成一個有效長度的隨機字串，像是，
$memcache_key = "vCH1vGWJxfSeofSAs0K5PA" - 將帶鑰匙
$memcache_key的值123放入Memcache(3600秒，一小時) - 向用戶顯示按鈕
- 配置webhook處理器以處理
/start開頭的傳入訊息中傳遞的參數查詢Memcached。如果金鑰存在，那就記錄傳遞給webhook的chat_id作為使用者123的telegram_chat_id。從Memcache刪除金鑰。 - 現在，當我們想要發送通知給用戶
123的時候，檢查他們是否擁有字段telegram_chat_id。如果擁有，那就在Bot API中使用方法sendMessage在Telegram中向他們發送訊息。
Location and Number
有些bot需要用戶提供額外的資料才能正常的工作。舉例來說，瞭解用戶位置有助於提供更多相關地理特定結果。用戶電話號碼對整合其它服務(像是銀行)非常有用。
bots可以使用特殊按鈕詢問用戶的位置與電話號碼。注意到，電話號碼與位置的請求按鈕都只能在私密聊天中使用。
當這些按鈕被按下的時候，Telegram客戶端將顯示確認警報，並告知用戶將要發生的情況。
6. BotFather
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所需要的。確保你的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 - 請求位置資料來提供基於位置的inline結果。
- /setjoingroups — 切換是否可以將你的bot加入群組內。任何的bot都必須能夠處理私人訊息，但是如果你的bot並不是設計來在群組內工作的，你可以關閉這個。
- /setprivacy — 設置當你的bot被加入群組的時候會收到的訊息。當隱私模式被關閉的時候，bot將會將到所有的訊息。我們建立保留啟用隱私模式。你將需要重新加入bot到已存在的群組，這個改變才會生效。
Manage games
- /newgame — 建立新的遊戲。
- /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非常有用。值愈大，差異愈顯著。
Too few replies to incoming **private messages**. Conversion rate: **{value}**
你的bot沒有回應發給它的所有訊息(在過去三個五分鐘內的至少兩個，其bot的請求/響求轉換率太低)。為了提供好的用戶體驗，請回覆發送到你的bot的所有訊息。通過呼叫send…方法來響應消息更新。(例如sendMessage)
Too few answers to **inline queries**. Conversion rate: **{value}**
你的bot沒有回覆發送給它的所有inline queries，計算方法與上面相同。透過呼叫answerInlineQuery響應inline_query更新。
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.
如果你有任何問題，請查閱我們的Bot FAQ »
沒有留言:
張貼留言