API UO Messenger zh tw

UO.Messenger

Русский · English · Українська · Deutsch · Français · Italiano · Español · 繁體中文 · 日本語 · 한국어

ClassicUO • Runtime API

建立 Telegram、Discord 或 Viber 文字訊息物件。腳本可通知採集完成，或檢查指定使用者的停止要求。建立物件不會登入機器人，也不會傳送訊息。

完整語法

UO.Messenger(provider:String) -> Object

參數

• provider — String：「telegram」、「discord」或「viber」，不區分大小寫。其他值會產生錯誤。

傳回值

Messenger Object。訊息、傳送者和聊天 ID 一律是 String；請勿用 CInt/CDbl 轉換。

行為

• Provider() → String；Connected() → 1/0（True/False）：服務名稱與最近的驗證狀態，不保證此刻網路可用。
• Connect(token) → Unit 驗證機器人權杖。ConnectFromFile(path) → Unit 讀取最多 1024 位元組的 UTF-8 權杖檔案；相對路徑以目前腳本資料夾為準。重新連線前須呼叫 Disconnect。
• Disconnect() → Unit 停止本機接收並清除權杖和游標，可再次連線。Dispose() → Unit 永久關閉物件。
• SendMessage(text, recipient) → String：服務接受的訊息 ID。recipient 是字串形式的 Telegram chat ID、Discord channel ID 或 Viber 訂閱者 ID。文字長度分別為 1..4096/2000/7000；Viber JSON 還須 ≤30000 位元組。Discord 的 everyone／角色提及功能關閉。
• WatchChannel(channelId) → Unit：僅 Discord，記住目前最後一則訊息，之後只讀新訊息。WatchChannel(channelId, afterMessageId) → Unit 從指定字串 ID 之後開始；「0」包含歷史。最多 32 個頻道。
• Receive(timeoutSeconds) → Array；Receive() 使用 0。範圍 0..20 秒；空陣列表示沒有可讀文字。Telegram 使用長輪詢，Discord 輪詢頻道，Viber 讀取 webhook 佇列。單次網路請求最長可達 30 秒。
• MessengerMessage 的 Id()、SenderId()、SenderName()、ChatId()、Text() 均回傳 String。Telegram 頻道貼文可能沒有 SenderId。附件、非文字事件與 Discord 機器人訊息不回傳。
• RetryAfter() → Integer：服務限流後尚須等待的秒數。到期前不發出新 HTTP 請求。傳送失敗不自動重試，因為訊息可能已送達。
• StartReceiver(localPort, publicHttpsUrl) → Integer：僅 Viber，連接埠 1..65535，回傳本機連接埠。公開 HTTPS 網址須以 /viber/ 結尾，且事先將 POST 轉送至 127.0.0.1:連接埠/viber/，保留原始內容與簽章標頭。此方法會註冊 webhook。
• 需要機器人權杖。Telegram 若已有 webhook，會拒絕連線且不刪除它。Discord 需要頻道讀寫權限與 MESSAGE_CONTENT；Viber 只傳給訂閱者。
• 完整解析批次後才更新游標。Telegram／Discord 每次最多 100 筆，請再次呼叫 Receive 讀取後續批次。Viber 使用 HMAC-SHA256，佇列上限 100，對最近 2048 個 ID 去重；滿載回傳 HTTP 503。代理須提供 Content-Length；本機入口不接受 chunked。
• 權杖不會寫入設定檔、錯誤內容或 Connect 引數歷程。ConnectFromFile 也避免建立偵錯器可見的權杖變數。請勿公開權杖檔案。
• 在程序內建立物件，同時最多 32 個。Using／Dispose、正常結束、錯誤與 Stop 都會釋放資源。關閉 Viber 接收器不會刪除遠端 webhook。收到的文字不會當成程式碼執行；腳本自行設定可信任傳送者。

內部函式：從呼叫到結果

CreateMessenger 不進行網路操作，並將資源綁定於本次腳本執行。

1. CreateMessenger

CreateMessenger 不進行網路操作，並將資源綁定於本次腳本執行。

Messenger Object。訊息、傳送者和聊天 ID 一律是 String；請勿用 CInt/CDbl 轉換。

專案原始碼: external/InjectionScript/src/InjectionScript/Runtime/InjectionRuntime.cs; 函式 CreateMessenger.

2. RequestAsync

RequestAsync 建立服務專用 JSON 與標頭、檢查狀態，回應限制 2 MiB，請求限制 30 秒；取消腳本會中斷等待。

錯誤可由 Try/Catch 處理；Stop 仍是取消執行。傳送錯誤不代表一定未送達。

專案原始碼: external/InjectionScript/src/InjectionScript/Runtime/Messaging/MessengerClient.cs; 函式 RequestAsync.

3. Accept

Accept 驗證 Viber 簽章與 UTF-8 後將文字入列。Receive 交給腳本；網路執行緒不呼叫腳本處理程序。

錯誤可由 Try/Catch 處理；Stop 仍是取消執行。傳送錯誤不代表一定未送達。

專案原始碼: external/InjectionScript/src/InjectionScript/Runtime/Messaging/ViberReceiver.cs; 函式 Accept.

入口程序結束、出錯或 Stop 時會關閉資源。

範例

Telegram：通知工作完成

# Telegram：通知工作完成
#
# 建立 Telegram、Discord 或 Viber 文字訊息物件。腳本可通知採集完成，或檢查指定使用者的停止要求。建立物件不會登入機器人，也不會傳送訊息。
#
# Messenger Object。訊息、傳送者和聊天 ID 一律是 String；請勿用 CInt/CDbl 轉換。

SUB Main()
    # 將 telegram-token.txt 放在腳本旁，並把 12345678 改為自己的 chat ID。傳送一次通知並回傳字串 ID，不代表使用者已讀。
    # 請設定自己的機器人。範例僅使用本機測試回應，未聯絡真實收件者。

    Dim bot = UO.Messenger("telegram")
    Using bot
        bot.ConnectFromFile("telegram-token.txt")
        Dim messageId = bot.SendMessage("Harvest finished", "12345678")
        Return messageId
    End Using
END SUB

參數與執行說明:

• 將 telegram-token.txt 放在腳本旁，並把 12345678 改為自己的 chat ID。傳送一次通知並回傳字串 ID，不代表使用者已讀。
• 請設定自己的機器人。範例僅使用本機測試回應，未聯絡真實收件者。

Discord：驗證停止要求

# Discord：驗證停止要求
#
# 建立 Telegram、Discord 或 Viber 文字訊息物件。腳本可通知採集完成，或檢查指定使用者的停止要求。建立物件不會登入機器人，也不會傳送訊息。
#
# Messenger Object。訊息、傳送者和聊天 ID 一律是 String；請勿用 CInt/CDbl 轉換。

SUB Main()
    # 填入頻道及允許的傳送者 ID。True 表示本次收到該使用者的 stop。此範例本身不停止移動，請把結果用於工作迴圈條件。
    # 請設定自己的機器人。範例僅使用本機測試回應，未聯絡真實收件者。

    Dim bot = UO.Messenger("discord")
    Using bot
        bot.ConnectFromFile("discord-token.txt")
        bot.WatchChannel("123456789012345678")
        Dim messages = bot.Receive(5)
        For Each message In messages
            If message.SenderId() = "987654321098765432" AndAlso LCase(Trim(message.Text())) = "stop" Then
                Return True
            End If
        Next
        Return False
    End Using
END SUB

參數與執行說明:

• 填入頻道及允許的傳送者 ID。True 表示本次收到該使用者的 stop。此範例本身不停止移動，請把結果用於工作迴圈條件。
• 請設定自己的機器人。範例僅使用本機測試回應，未聯絡真實收件者。

Viber：接收簽署文字

# Viber：接收簽署文字
#
# 建立 Telegram、Discord 或 Viber 文字訊息物件。腳本可通知採集完成，或檢查指定使用者的停止要求。建立物件不會登入機器人，也不會傳送訊息。
#
# Messenger Object。訊息、傳送者和聊天 ID 一律是 String；請勿用 CInt/CDbl 轉換。

SUB Main()
    # 腳本旁需要 viber-token.txt 及
    # viber-settings.json：{"port":8787,"publicUrl":"https://YOUR-HOST/viber/"}。設定 HTTPS 轉送並替換
    # trusted-subscriber-id。回傳該使用者的文字或空字串。
    # 請設定自己的機器人。範例僅使用本機測試回應，未聯絡真實收件者。

    Dim settings = JsonLoad("viber-settings.json")
    Dim bot = UO.Messenger("viber")
    Using bot
        bot.ConnectFromFile("viber-token.txt")
        bot.StartReceiver(settings["port"], settings["publicUrl"])
        Dim messages = bot.Receive(5)
        For Each message In messages
            If message.SenderId() = "trusted-subscriber-id" Then
                Return message.Text()
            End If
        Next
        Return ""
    End Using
END SUB

參數與執行說明:

• 腳本旁需要 viber-token.txt 及 viber-settings.json：{"port":8787,"publicUrl":"https://YOUR-HOST/viber/"}。設定 HTTPS 轉送並替換 trusted-subscriber-id。回傳該使用者的文字或空字串。
• 請設定自己的機器人。範例僅使用本機測試回應，未聯絡真實收件者。