API UO Messenger en

UO.Messenger

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

ClassicUO • Runtime API

Creates a text messenger for Telegram, Discord, or Viber. A script can report that harvesting finished or inspect a stop request from an approved sender. Construction neither authenticates the bot nor sends a message.

Exact syntax

UO.Messenger(provider:String) -> Object

Parameters

• provider — String: "telegram", "discord", or "viber", case-insensitive. Other values raise an error.

Returns

Messenger Object, not a Boolean or ID. Message, sender, and chat IDs are always String; compare them with strings, never convert them through CInt/CDbl.

Behavior

• Provider() → String; Connected() → 1/0 (True/False): provider and last authentication state, not a guarantee of current Internet availability.
• Connect(token) → Unit: authenticates a bot. ConnectFromFile(path) → Unit: reads a UTF-8 token file up to 1024 bytes; relative paths use the current script folder. Disconnect before connecting again. Failures are catchable with Try/Catch.
• Disconnect() → Unit: stops local reception and clears token/cursors; reconnect is allowed. Dispose() → Unit: permanently closes the object.
• SendMessage(text, recipient) → String: accepted message ID. Recipient is a Telegram chat ID, Discord channel ID, or Viber subscriber ID, supplied as text. Text limits are 4096/2000/7000 respectively; Viber JSON must also fit 30000 bytes. Empty text is rejected. Discord everyone/role mentions are disabled.
• WatchChannel(channelId) → Unit: Discord only; records the latest message and receives later ones. WatchChannel(channelId, afterMessageId) → Unit: starts after that string ID; "0" includes history. Up to 32 channels per object.
• Receive(timeoutSeconds) → Array; Receive() uses 0. Timeout 0..20 seconds; an empty array means no available text. Telegram uses long polling, Discord polls watched channels, Viber drains its webhook queue. A network request can take up to 30 seconds.
• Each MessengerMessage exposes Id(), SenderId(), SenderName(), ChatId(), Text() → String. Telegram channel posts may lack SenderId. Attachments, nontext events, and Discord bot messages are omitted.
• RetryAfter() → Integer: seconds remaining after a service rate limit. No further HTTP requests run before that deadline. Failed sends are never retried automatically because delivery may already have occurred.
• StartReceiver(localPort, publicHttpsUrl) → Integer: Viber only; port 1..65535, returns the bound local port. The public HTTPS URL must end in /viber/ and already forward POST to 127.0.0.1:port/viber/ preserving the raw body and signature header. Registers the Viber webhook.
• Use a bot token, not a personal account password. Telegram rejects an existing webhook without deleting it. Discord needs channel read/send permissions and MESSAGE_CONTENT to expose text; Viber sends to subscribers.
• Receive commits cursors after decoding the entire batch. Telegram/Discord return up to 100 records per request; call Receive again for later batches. WatchChannel without a second argument skips old Discord history.
• Viber verifies raw-body HMAC-SHA256. The queue holds 100 messages and deduplicates the last 2048 accepted IDs; overflow returns HTTP 503 for provider retry. The HTTPS forwarder must provide Content-Length; chunked local requests are rejected.
• Tokens are not saved in profiles, error details, or Connect argument history. Prefer ConnectFromFile so the token is not in a script variable visible to the debugger. Never publish token files.
• Create inside a procedure, at most 32 live objects. Using/Dispose closes early. Completion, error, and script Stop close all owned objects. Closing the Viber receiver does not remove the remote webhook.
• Text transport only: incoming text is never executed as code and no game account is connected. The script defines trusted senders.

Internal functions: from call to result

CreateMessenger constructs without network I/O and assigns ownership to the current script run.

1. CreateMessenger

CreateMessenger constructs without network I/O and assigns ownership to the current script run.

Messenger Object, not a Boolean or ID. Message, sender, and chat IDs are always String; compare them with strings, never convert them through CInt/CDbl.

Project source: external/InjectionScript/src/InjectionScript/Runtime/InjectionRuntime.cs; function CreateMessenger.

2. RequestAsync

RequestAsync encodes provider-specific JSON and headers and checks HTTP/provider status. Responses are limited to 2 MiB and requests to 30 seconds; script cancellation interrupts waiting.

Failures throw catchable errors; Stop remains cancellation. A send error does not prove nondelivery.

Project source: external/InjectionScript/src/InjectionScript/Runtime/Messaging/MessengerClient.cs; function RequestAsync.

3. Accept

Accept authenticates the Viber signature, decodes UTF-8, and queues bounded text. Receive transfers messages to the script; no script callback runs on the network thread.

Failures throw catchable errors; Stop remains cancellation. A send error does not prove nondelivery.

Project source: external/InjectionScript/src/InjectionScript/Runtime/Messaging/ViberReceiver.cs; function Accept.

Resources are released when the entry procedure finishes, including failure and Stop.

Examples

Telegram: report completed work

# Telegram: report completed work
#
# Creates a text messenger for Telegram, Discord, or Viber. A script can report that harvesting
# finished or inspect a stop request from an approved sender. Construction neither authenticates
# the bot nor sends a message.
#
# Messenger Object, not a Boolean or ID. Message, sender, and chat IDs are always String;
# compare them with strings, never convert them through CInt/CDbl.

SUB Main()
    # Place telegram-token.txt beside the script and replace 12345678 with your chat ID. Sends one
    # notification and returns its string ID; provider acceptance does not prove human readership.
    # Configure your own bot. Examples were executed against local fixtures, without contacting real
    # recipients.

    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

Parameter and execution notes:

• Place telegram-token.txt beside the script and replace 12345678 with your chat ID. Sends one notification and returns its string ID; provider acceptance does not prove human readership.
• Configure your own bot. Examples were executed against local fixtures, without contacting real recipients.

Discord: accept a stop request from one sender

# Discord: accept a stop request from one sender
#
# Creates a text messenger for Telegram, Discord, or Viber. A script can report that harvesting
# finished or inspect a stop request from an approved sender. Construction neither authenticates
# the bot nor sends a message.
#
# Messenger Object, not a Boolean or ID. Message, sender, and chat IDs are always String;
# compare them with strings, never convert them through CInt/CDbl.

SUB Main()
    # Set your channel and approved sender IDs. True means this check received their text stop; the
    # example itself does not stop movement. Use the result as a condition in your own work loop.
    # Configure your own bot. Examples were executed against local fixtures, without contacting real
    # recipients.

    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

Parameter and execution notes:

• Set your channel and approved sender IDs. True means this check received their text stop; the example itself does not stop movement. Use the result as a condition in your own work loop.
• Configure your own bot. Examples were executed against local fixtures, without contacting real recipients.

Viber: receive authenticated text

# Viber: receive authenticated text
#
# Creates a text messenger for Telegram, Discord, or Viber. A script can report that harvesting
# finished or inspect a stop request from an approved sender. Construction neither authenticates
# the bot nor sends a message.
#
# Messenger Object, not a Boolean or ID. Message, sender, and chat IDs are always String;
# compare them with strings, never convert them through CInt/CDbl.

SUB Main()
    # Create viber-settings.json beside the script:
    # {"port":8787,"publicUrl":"https://YOUR-HOST/viber/"}; configure HTTPS forwarding and
    # viber-token.txt. Replace trusted-subscriber-id. Returns their text, or an empty string.
    # Configure your own bot. Examples were executed against local fixtures, without contacting real
    # recipients.

    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

Parameter and execution notes:

• Create viber-settings.json beside the script: {"port":8787,"publicUrl":"https://YOUR-HOST/viber/"}; configure HTTPS forwarding and viber-token.txt. Replace trusted-subscriber-id. Returns their text, or an empty string.
• Configure your own bot. Examples were executed against local fixtures, without contacting real recipients.