originchats

Write bots for originChats servers: answer commands and slash commands, react to events, post embeds and polls, and manage channels.

import "std:originchats"

std:originchats is a bot framework for originChats servers. It handles the connection, the login, reconnecting and matching replies to requests, so a bot is a list of handlers. You react to messages and slash commands, and reply with text, embeds and polls.

A bot talks to a live server, so those examples compile but don't run here. Embeds and polls are plain data you can build and look at, so they run in the page.

The smallest bot#

originchats.new(url, options) makes a client. command(prefix, handler) answers messages that start with a word, and run connects and blocks:

main.osl

import "std:originchats"

*originchats.Client client = originchats.new("wss://chats.example.com", {token: "your rotur token"})

client.command("!ping", def(*originchats.Message msg) (
  msg.reply("pong, " ++ msg.user()).unwrap()
))

client.run("your rotur token").unwrap()

Click the code to edit it

Send !ping in a channel the bot can see and it answers. The handler receives a Message. msg.user() is who wrote it, msg.content() is the text with the prefix removed, and msg.args() splits it into words.

Reading what was said#

A command's text arrives without the prefix, so a command is a function of its arguments:

main.osl

import "std:originchats"

*originchats.Client client = originchats.new("wss://chats.example.com", {token: "your rotur token"})

client.command("!add", def(*originchats.Message msg) (
  string[] parts = msg.args()
  if parts.len != 2 (
    msg.reply("usage: !add 1 2").unwrap()
    return
  )
  number total = parts[1].as<number> + parts[2].as<number>
  msg.reply("= " ++ total).unwrap()
))

client.run("your rotur token").unwrap()

Click the code to edit it

Messages have more to look at: isReply(), mentionsMe(), attachments(), embeds() and reactions(). They can be acted on, too: react("👍"), edit(text), pin() and delete().

Events#

client.on(event, handler) handles anything the server sends. "ready" runs after every connect, "message" for each new message no command took (the bot's own are skipped), and a server event name such as "reaction_add" or "user_join" gets the raw packet. Handlers run on their own threads, and a throw is printed instead of stopping the bot:

main.osl

import "std:originchats"

*originchats.Client client = originchats.new("wss://chats.example.com", {token: "your rotur token"})

client.on("ready", def(any c, any packet) ( log "connected as " ++ client.username() ))

client.on("message", def(*originchats.Message msg) (
  if msg.mentionsMe() (
    msg.react("👀").unwrap()
  )
))

client.run("your rotur token").unwrap()

Click the code to edit it

Quick check

You register client.command("!ping", ...) and client.on("message", ...). A user sends !ping. Which handlers run?

Slash commands#

A slash command has a name, a description and typed inputs, which the server shows in its menu. Build one with slashCommand(name), add inputs, then give it a handler with fn:

main.osl

import "std:originchats"
import "std:random"

*originchats.Client client = originchats.new("wss://chats.example.com", {token: "your rotur token"})

client.slashCommand("roll")
  .description("Roll a die")
  .addInteger("sides", {description: "How many sides", min: 2})
  .fn(def(*originchats.Slash call) (
    int sides = 6
    if call.has("sides") ( sides = call.argNum("sides").as<int> )
    call.respond("You rolled " ++ random.int(1, sides)).unwrap()
  ))

client.run("your rotur token").unwrap()

Click the code to edit it

addString, addBoolean, addNumber, addUser and addChoices make other inputs, ephemeral(true) makes the answer visible only to the caller, and whitelistRoles limits who may run it. In the handler, call.argStr, call.argNum, call.argBool and call.arg read the inputs, and call.invoker() says who ran it.

Channels#

client.channel(name) is a handle for a channel. Nothing is sent until you use it:

main.osl

import "std:originchats"

*originchats.Client client = originchats.new("wss://chats.example.com", {token: "your rotur token"})
client.start().unwrap()

auto general = client.channel("general")
general.send("Deploy finished").unwrap()

for item in general.messages(5).unwrap() (
  auto msg = item.<originchats.Message>
  log msg.user() ++ ": " ++ msg.content()
)
client.stop()

Click the code to edit it

The list a read returns holds untyped items, so narrow each one with item.<originchats.Message>. start() connects and waits until the server is ready, which suits a script that does a job and exits. run() is for a bot that stays. Channels can also make threads, pin messages, search and manage webhooks.

Embeds#

An embed is a card attached to a message: a title, text, fields, a footer, an image. originchats.newEmbed(options) starts one, each method adds to it and returns it, and build() gives the data a server receives. That is plain data, so you can look at it:

main.osl

import "std:originchats"

auto embed = originchats.newEmbed({
  title: "Build finished",
  description: "All checks passed",
  color: "#22aa55"
})
  .addField("Branch", "main", {inline: true})
  .addField("Time", "42s", {inline: true})
  .withFooter("CI")
  .build()

log embed.title
log embed.fields.len
log embed

Click the code to edit it

Change the colour or add a field and run it again. To post it, pass it to a send: channel.send("", {embeds: [embed]}).

Polls#

originchats.newPoll(question, choices, options) builds a poll embed. Choices are strings or {text, emoji}, and multiselect lets people pick several:

main.osl

import "std:originchats"

auto poll = originchats.newPoll(
  "Lunch?",
  ["Pizza", {text: "Sushi", emoji: "🍣"}],
  {multiselect: true}
).build()
log poll

Click the code to edit it

After it is posted, client.vote(pollID, options), client.poll(pollID) and client.endPoll(pollID) work with it.

Your turn

A status card

Build an embed titled Status with the description All good and one field named Uptime with the value 99.9%. Print its fields length.

main.osl

import "std:originchats"

auto embed = originchats.newEmbed({title: "Status"}).build()
log embed.title

import "std:originchats"

auto embed = originchats.newEmbed({title: "Status"}).build()
log embed.title

Ctrl Enter runs

Expected output

Server management#

A bot with the right permissions can manage the server: createChannel, deleteChannel, createRole, setRoles, kickUser, banUser, muteUser, setNickname and uploadFile. Reads such as users(), usersOnline(), roles() and channels() return results too. Check client.supports(command) before using something an older server may lack.

API reference#

282 members, generated from the std:originchats source of OSL 9.3.0.

Functions

#originchats.embed(any ...args) *originchats.Embed

Deprecated. Deprecated: use originchats.newEmbed({title, description}) instead.

embed starts a rich embed: embed(title?, description?).

#originchats.new(string url, object? options) *originchats.Client

new builds a bot client for url; start() or run() connects it. Options: token, username, password, register, serverPassword, invite, clientName, timeout (milliseconds, default 10000), ignoreSelf, signing and roturURL. Requests fail with StateError, TimeoutError, PermissionError, NotFoundError, ValueError or RuntimeError.

#originchats.newEmbed(object? options) *originchats.Embed

newEmbed starts a rich embed. Options: title, description, url (strings), color ("#rrggbb" or {r, g, b}). Chain the embed's methods to fill it in.

#originchats.newPoll(string question, array choices, object? options) *originchats.Embed

newPoll makes a poll embed asking question. choices are strings or {text, emoji} objects. Options: multiselect (boolean).

#originchats.poll(string question, array choices, any ...multiselect) *originchats.Embed

Deprecated. Deprecated: use originchats.newPoll(question, choices, {multiselect}) instead.

poll makes a poll embed: poll(question, options, multiselect?).

Constants

string originchats.boolean

Boolean is the "bool" input type for slashCommand.addInput.

string originchats.choice

Choice is the "enum" input type for slashCommand.addInput.

string originchats.integer

Integer is the "int" input type for slashCommand.addInput.

string originchats.number

Number is the "float" input type for slashCommand.addInput.

string originchats.string

String is the "str" input type for slashCommand.addInput.

string originchats.username

Username is the "user" input type for slashCommand.addInput.

`*originchats.Client`

#client.attachments(int offset, int limit) result<array, error>

attachments returns up to limit of the bot's uploaded attachments, skipping the first offset.

#client.ban(string username) result<unit, error>

ban bans username.

#client.call(object payload, object? options) result<any, error>

call sends a raw command object (with a cmd key, in the server's format) and returns the server's answer, for commands the client has no method for. Options: wait (boolean, default true; false sends without waiting and returns null). Fails like any request.

#client.channel(string name) *originchats.Channel

channel is a handle for the channel name. Nothing is sent until you use it.

#client.channels() result<array, error>

channels returns the server's channels.

#client.clientName(string name) *originchats.Client

Deprecated. Deprecated: use originchats.new(url, {clientName}) instead.

clientName sets the reported client name and returns the client.

#client.command(string prefix, any handler)

command runs handler(message) for messages starting with prefix (as a whole word), with the prefix stripped from message.content(). The first matching command wins and the message event doesn't fire for it.

#client.connect(any ...token) boolean

Deprecated. Deprecated: use client.start() instead, which waits for the login and fails with a typed error.

connect opens the websocket and returns whether that worked; the login finishes in the background and "ready" handlers run once it is done.

#client.connected() boolean

Deprecated. Deprecated: use client.isConnected() instead.

connected reports whether the websocket is open.

#client.createChannel(string name, object? options) result<unit, error>

createChannel creates a text channel called name. fields are extra channel fields in the server's format, such as {type: "voice"} or {description: "..."}.

#client.createRole(object role) result<unit, error>

createRole creates a role from its fields (name, color, permissions, ... in the server's format).

#client.delete(string channel, string id) boolean

Deprecated. Deprecated: use (channel.get(id)).delete() instead.

delete deletes a message by channel and id.

#client.deleteChannel(string name) result<unit, error>

deleteChannel deletes the channel name.

#client.deleteRole(string name) result<unit, error>

deleteRole deletes the role name.

#client.deleteWebhook(string id) result<unit, error>

deleteWebhook deletes the webhook id.

#client.details() any

details is the whole handshake object (server, limits, capabilities, permissions, ...), or null before the handshake.

#client.dispatch(string raw)

Deprecated. Deprecated: an internal hook; servers deliver packets themselves.

dispatch handles one raw packet as if the server had sent it.

#client.edit(string channel, string id, string content) boolean

Deprecated. Deprecated: use (channel.get(id)).edit(content) instead.

edit edits a message by channel and id.

#client.emojis() result<object, error>

emojis returns the server's custom emojis.

#client.endPoll(string pollID) result<unit, error>

endPoll closes the poll pollID.

#client.get(string key) any

get returns the value set under key, or null.

#client.httpURL() result<string, error>

httpURL is the server's HTTP origin, derived from the websocket address. Fails with ParseError when the address isn't a URL.

#client.ignoreSelf(boolean v) *originchats.Client

Deprecated. Deprecated: use originchats.new(url, {ignoreSelf}) instead.

ignoreSelf sets whether the bot's own messages are skipped and returns the client.

#client.invite(string code) *originchats.Client

Deprecated. Deprecated: use originchats.new(url, {invite}) instead.

invite sets the invite code and returns the client.

#client.isConnected() boolean

isConnected reports whether the websocket is open (it may still be logging in).

#client.isReady() boolean

isReady reports whether the bot is logged in and ready.

#client.isSigning() boolean

isSigning reports whether outgoing messages are signed: signing is on, the server supports it and the bot's rotur key was loaded.

#client.kick(string username, any ...reason) boolean

Deprecated. Deprecated: use client.kickUser(username, {reason}) instead.

kick disconnects a user: kick(username, reason?).

#client.kickUser(string username, object? options) result<unit, error>

kickUser disconnects username. Options: reason (string).

#client.latency() result<number, error>

latency measures the round trip to the server in ms.

#client.limits() any

limits is the server's limits object from the handshake, or null before it.

#client.me() any

me is the bot's user object from the server, or null before it is ready.

#client.message(string channel, string id) object

Deprecated. Deprecated: use client.channel(name).get(id) instead.

message returns one message of a channel as an object, or {}.

#client.messages(string channel, number limit) array

Deprecated. Deprecated: use client.channel(name).messages(limit) instead.

messages returns recent messages of a channel.

#client.mute(string username, number seconds, any ...reason) boolean

Deprecated. Deprecated: use client.muteUser(username, duration, {reason}) instead, with the duration in ms.

mute times a user out: mute(username, seconds, reason?).

#client.muteUser(string username, number duration, object? options) result<unit, error>

muteUser times username out for duration ms (counted in whole seconds). Options: reason (string).

#client.now() number

now is the current time on the server clock, in unix ms.

#client.off(string event, any handler)

off removes a handler added with on(event, handler).

#client.ok(object payload) boolean

Deprecated. Deprecated: use client.call(payload) instead, which fails with a typed error.

ok sends a raw command and reports whether the server accepted it.

#client.on(string event, any handler)

on adds handler for event. "ready" runs as handler(client, packet) after every (re)connect, "disconnect" as handler(client) when a ready connection drops, "message" as handler(message) for each new message no prefix command took (the bot's own are skipped unless ignoreSelf is false), and any server command name ("message_new", "message_edit", "reaction_add", "typing", "user_join", "thread_create", "poll_vote", "error", ...) or "*" for every packet as handler(client, packet). Handlers run on background threads; a throw is printed and the bot keeps running.

#client.onDisconnect(any handler)

Deprecated. Deprecated: use client.on("disconnect", handler) instead.

onDisconnect runs handler(client) when a ready connection drops.

#client.onError(any handler)

Deprecated. Deprecated: use client.on("error", handler) instead.

onError runs handler(client, packet) for server errors.

#client.onMessageDelete(any handler)

Deprecated. Deprecated: use client.on("message_delete", handler) instead.

onMessageDelete runs handler(client, packet) for deletions.

#client.onMessageEdit(any handler)

Deprecated. Deprecated: use client.on("message_edit", handler) instead.

onMessageEdit runs handler(client, packet) for edits.

#client.onMessageNew(any handler)

Deprecated. Deprecated: use client.on("message", handler) instead.

onMessageNew runs handler(message) for new messages.

#client.onMessagePin(any handler)

Deprecated. Deprecated: use client.on("message_pin", handler) instead.

onMessagePin runs handler(client, packet) for pins.

#client.onMessageUnpin(any handler)

Deprecated. Deprecated: use client.on("message_unpin", handler) instead.

onMessageUnpin runs handler(client, packet) for unpins.

#client.onMessagesDelete(any handler)

Deprecated. Deprecated: use client.on("messages_delete", handler) instead.

onMessagesDelete runs handler(client, packet) for bulk deletions.

#client.onPollEnd(any handler)

Deprecated. Deprecated: use client.on("poll_end", handler) instead.

onPollEnd runs handler(client, packet) when a poll ends.

#client.onPollVote(any handler)

Deprecated. Deprecated: use client.on("poll_vote", handler) instead.

onPollVote runs handler(client, packet) for poll votes.

#client.onRateLimit(any handler)

Deprecated. Deprecated: use client.on("rate_limit", handler) instead.

onRateLimit runs handler(client, packet) when rate limited.

#client.onReactionAdd(any handler)

Deprecated. Deprecated: use client.on("reaction_add", handler) instead.

onReactionAdd runs handler(client, packet) for added reactions.

#client.onReactionRemove(any handler)

Deprecated. Deprecated: use client.on("reaction_remove", handler) instead.

onReactionRemove runs handler(client, packet) for removed reactions.

#client.onReady(any handler)

Deprecated. Deprecated: use client.on("ready", handler) instead.

onReady runs handler(client) when the bot is ready.

#client.onStatus(any handler)

Deprecated. Deprecated: use client.on("status_get", handler) and client.on("user_status", handler) instead.

onStatus runs handler(client, packet) for status packets.

#client.onThreadCreate(any handler)

Deprecated. Deprecated: use client.on("thread_create", handler) instead.

onThreadCreate runs handler(client, packet) for new threads.

#client.onThreadDelete(any handler)

Deprecated. Deprecated: use client.on("thread_delete", handler) instead.

onThreadDelete runs handler(client, packet) for deleted threads.

#client.onThreadUpdate(any handler)

Deprecated. Deprecated: use client.on("thread_update", handler) instead.

onThreadUpdate runs handler(client, packet) for thread changes.

#client.onTyping(any handler)

Deprecated. Deprecated: use client.on("typing", handler) instead.

onTyping runs handler(client, packet) for typing indicators.

#client.onUnreads(any handler)

Deprecated. Deprecated: use client.on("unreads_update", handler) instead.

onUnreads runs handler(client, packet) for unread updates.

#client.onUserConnect(any handler)

Deprecated. Deprecated: use client.on("user_connect", handler) instead.

onUserConnect runs handler(client, packet) when a user connects.

#client.onUserDisconnect(any handler)

Deprecated. Deprecated: use client.on("user_disconnect", handler) instead.

onUserDisconnect runs handler(client, packet) when a user disconnects.

#client.onUserJoin(any handler)

Deprecated. Deprecated: use client.on("user_join", handler) instead.

onUserJoin runs handler(client, packet) when a user joins.

#client.onUserLeave(any handler)

Deprecated. Deprecated: use client.on("user_leave", handler) instead.

onUserLeave runs handler(client, packet) when a user leaves.

#client.onUserUpdate(any handler)

Deprecated. Deprecated: use client.on("user_update", handler) instead.

onUserUpdate runs handler(client, packet) when a user changes.

#client.password(string pw) *originchats.Client

Deprecated. Deprecated: use originchats.new(url, {serverPassword}) instead.

password sets the server password and returns the client.

#client.pin(string channel, string id) boolean

Deprecated. Deprecated: use message.pin() instead.

pin pins a message by channel and id.

#client.pings(any ...limit) array

Deprecated. Deprecated: use client.recentPings({limit}) instead.

pings returns recent mentions: pings(limit?).

#client.poll(string pollID) result<object, error>

poll returns the poll pollID with its votes.

#client.react(string channel, string id, string emoji) boolean

Deprecated. Deprecated: use message.react(emoji) instead.

react reacts to a message by channel and id.

#client.ready() boolean

Deprecated. Deprecated: use client.isReady() instead.

ready reports whether the bot is ready.

#client.recentPings(object? options) result<array, error>

recentPings returns recent messages that mention the bot. Options: limit (number).

#client.register(string username, string password) *originchats.Client

Deprecated. Deprecated: use originchats.new(url, {username, password, register: true}) instead.

#client.request(object payload) object

Deprecated. Deprecated: use client.call(payload) instead, which fails with a typed error.

request sends a raw command and returns the reply, or an object with an error key.

#client.roles() result<object, error>

roles returns an object of role name to role.

#client.roturApi(string base) *originchats.Client

Deprecated. Deprecated: use originchats.new(url, {roturURL}) instead.

roturApi sets the rotur API origin and returns the client.

#client.run(any ...token) result<unit, error>

run starts the client and blocks until stop(), retrying a failed start with backoff (1 s up to 30 s, noted on stderr); later drops reconnect by themselves. Passing the token here is the older form of new(url, {token}). Fails with PermissionError when the server refuses the login, which retrying can't fix.

#client.search(string channel, string query, object? options) object

Deprecated. Deprecated: use client.channel(name).search(query, filters?) instead.

search searches a channel.

#client.send(string channel, string content) *originchats.Message

Deprecated. Deprecated: use client.channel(name).send(content) instead.

send posts content to a channel.

#client.sendCmd(object payload)

Deprecated. Deprecated: use client.call(payload, {wait: false}) instead.

sendCmd sends a raw command without waiting.

#client.sendEmbed(string channel, string content, *originchats.Embed embed) *originchats.Message

Deprecated. Deprecated: use client.channel(name).send(content, {embeds: [embed]}) instead.

sendEmbed posts content with an embed to a channel.

#client.sendRaw(object payload) *originchats.Message

Deprecated. Deprecated: use channel.send(content, options) instead.

sendRaw posts a raw message payload.

#client.sendThread(string threadID, string content) *originchats.Message

Deprecated. Deprecated: use client.thread(threadID).send(content) instead.

sendThread posts content to a thread.

#client.server() any

server is the server's info object from the handshake ({name, icon, ...}), or null before the handshake.

#client.serverTime() number

Deprecated. Deprecated: use client.now() instead, which is in unix ms.

serverTime is the server clock in seconds.

#client.serverUrl() string

Deprecated. Deprecated: use client.url() instead.

serverUrl is the websocket address.

#client.set(string key, any value)

set stores value under key on the client, for sharing state between handlers.

#client.setNickname(string username, string nickname) result<unit, error>

setNickname sets the nickname of username.

#client.setRoles(string username, array roles) result<unit, error>

setRoles replaces the role names username has.

#client.setSigning(boolean enabled)

setSigning turns message signing on or off while the bot runs.

#client.setStatus(string status, any ...text) boolean

Deprecated. Deprecated: use client.updateStatus(status, {text}) instead.

setStatus sets the status: setStatus(status, text?).

#client.signing(boolean enabled) *originchats.Client

Deprecated. Deprecated: use client.setSigning(enabled) or originchats.new(url, {signing}) instead.

signing turns signing on or off and returns the client.

#client.signingKey() object

Deprecated. Deprecated: use client.signingKeyID() instead, which never exposes the private key.

signingKey returns the rotur key record used for signing, private key included, or {}.

#client.signingKeyID() string?

signingKeyID is the id of the rotur key the bot signs with, or null when it isn't signing.

#client.signingURL() string

signingURL is the server URL bound into signatures (the handshake's signing_url, else url()).

#client.slash(object schema, any handler)

slash registers a slash command from a raw schema ({name, description, options, ...} in the server's format) with handler(call). Registering a name again replaces it. Throws ValueError when schema has no name.

#client.slashCommand(string name) *originchats.SlashCommand

slashCommand starts describing the slash command name (a leading "/" is dropped). Chain description and add* calls, then register it with fn(handler).

#client.start() result<unit, error>

start opens the connection, logs in and waits until the server says the bot is ready; dropped connections reconnect by themselves afterwards. Already started is a no-op. Fails with NetworkError when the server can't be reached, PermissionError when it refuses the login, TimeoutError when it doesn't answer within the timeout, and StateError when stop() interrupts it.

#client.stats() result<object, error>

stats returns the server's statistics as the server reports them.

#client.status(string username) result<object, error>

status returns the status object of username.

#client.stickers() result<object, error>

stickers returns the server's stickers.

#client.stop()

stop closes the connection, ends run() and fails waiting requests with StateError. start() or run() can start the client again. Stopping twice is a no-op.

#client.supports(string command) boolean

supports reports whether the server advertised the capability command.

#client.thread(string threadID) *originchats.Channel

thread is a handle for the thread threadID. Nothing is sent until you use it.

#client.timeout(number seconds) *originchats.Client

Deprecated. Deprecated: use originchats.new(url, {timeout}) instead, with the timeout in ms.

timeout sets the request timeout in seconds (0.001 to 300) and returns the client.

#client.typing(string channel)

Deprecated. Deprecated: use client.channel(name).typing() instead.

typing shows typing in a channel.

#client.unban(string username) result<unit, error>

unban lifts the ban on username.

#client.unpin(string channel, string id) boolean

Deprecated. Deprecated: use message.unpin() instead.

unpin unpins a message by channel and id.

#client.unreact(string channel, string id, string emoji) boolean

Deprecated. Deprecated: use message.unreact(emoji) instead.

unreact removes a reaction by channel and id.

#client.unreads() result<object, error>

unreads returns an object of channel to unread state.

#client.updateChannel(string name, object updates) result<unit, error>

updateChannel changes fields of the channel name (in the server's format).

#client.updateRole(object role) result<unit, error>

updateRole updates the role role.name with the other fields.

#client.updateStatus(string status, object? options) result<unit, error>

updateStatus sets the bot's status ("online", "idle", "dnd" or "offline"). Options: text (string shown with it).

#client.upload(string name, string data, string mimeType) object

Deprecated. Deprecated: use client.uploadBytes(name, data, {mimeType}) or client.uploadFile(path) instead.

upload stores text data as a file and returns the attachment object, or {} after printing why it failed.

#client.uploadBytes(string name, byte[] data, object? options) result<object, error>

uploadBytes stores data on the server as a file called name and returns the attachment object to pass to send({attachments}). Options: mimeType (default guessed from name's extension). Fails with NetworkError when the server can't be reached, the server's error kinds (by HTTP status) when it refuses the file, and the rotur errors when the bot's token can't be validated.

#client.uploadFile(string path, object? options) result<object, error>

uploadFile uploads the file at path; see uploadBytes. Options: name (default the file's name), mimeType (default guessed from the extension). Fails with NotFoundError when the file doesn't exist.

#client.url() string

url is the websocket address the client connects to.

#client.userID() string?

userID is the bot's user id, or null before it is ready.

#client.userRoles(string username) result<array, error>

userRoles returns the role names username has.

#client.username() string?

username is the bot's username, or null before it is ready.

#client.users() result<array, error>

users returns every member.

#client.usersBanned() result<array, error>

usersBanned returns the banned users.

#client.usersOnline() result<array, error>

usersOnline returns the members who are online.

#client.vote(string pollID, any ...optionIDs) result<unit, error>

vote votes in the poll pollID for one or more option ids (strings).

`*originchats.Channel`

#channel.ack(any ...messageID) boolean

Deprecated. Deprecated: use channel.markRead({messageID}) instead.

ack marks the channel read: ack(messageID?).

#channel.archive(boolean archived) result<unit, error>

archive archives (true) or unarchives (false) the thread. Throws StateError on a channel handle.

#channel.client() *originchats.Client

client is the client this handle belongs to.

#channel.createThread(string name) result<*originchats.Channel, error>

createThread starts a thread called name in the channel and returns it.

#channel.createWebhook(string name) result<object, error>

createWebhook creates a webhook called name in the channel and returns it (with its token).

#channel.delete(string id) boolean

Deprecated. Deprecated: use (channel.get(id)).delete() instead.

delete deletes the message id.

#channel.edit(string id, string content) boolean

Deprecated. Deprecated: use (channel.get(id)).edit(content) instead.

edit edits the message id.

#channel.editWith(string id, object payload) boolean

Deprecated. Deprecated: use (channel.get(id)).edit(content, options) instead.

editWith edits the message id with a raw payload.

#channel.get(string id) result<*originchats.Message, error>

get fetches the message id as a handle. Fails with NotFoundError when it doesn't exist.

#channel.info() result<object, error>

info returns the channel's or thread's info object.

#channel.isThread() boolean

isThread reports whether the handle is a thread.

#channel.join() result<unit, error>

join joins the thread. Throws StateError on a channel handle.

#channel.leave() result<unit, error>

leave leaves the thread. Throws StateError on a channel handle.

#channel.listThreads(object? options) result<array, error>

listThreads returns the channel's threads. Options: limit (number).

#channel.lock(boolean locked) result<unit, error>

lock locks (true) or unlocks (false) the thread. Throws StateError on a channel handle.

#channel.markRead(object? options) result<unit, error>

markRead marks the channel read. Options: messageID (string, read up to it).

#channel.message(string id) object

Deprecated. Deprecated: use channel.get(id) instead.

message returns the message id as an object, or {}.

#channel.messages(int limit) result<array, error>

messages returns up to limit of the newest messages as objects, oldest first.

#channel.messagesAround(string id, int above, int below) result<array, error>

messagesAround returns the message id with up to above older and below newer messages.

#channel.messagesBatch(array ids) result<array, error>

messagesBatch returns the messages with these ids.

#channel.messagesBefore(string id, int limit) result<array, error>

messagesBefore returns up to limit messages older than the message id.

#channel.name() string

name is the channel name ("" for a thread handle made with client.thread).

#channel.pin(string id) boolean

Deprecated. Deprecated: use message.pin() instead.

pin pins the message id.

#channel.pinThread() result<unit, error>

pinThread pins the thread in its channel. Throws StateError on a channel handle.

#channel.pinned() result<array, error>

pinned returns the pinned messages.

#channel.react(string id, string emoji) boolean

Deprecated. Deprecated: use message.react(emoji) instead.

react reacts to the message id.

#channel.remove() result<unit, error>

remove deletes the thread. Throws StateError on a channel handle.

#channel.rename(string name) result<unit, error>

rename renames the thread. Throws StateError on a channel handle.

#channel.replies(string id) array

Deprecated. Deprecated: use message.replies() instead.

replies returns the replies to the message id, or [].

#channel.search(string query, object? options) result<object, error>

search searches messages for query and returns {results, total, has_more}. filters is passed to the server as-is (such as {pinned: true}).

#channel.send(string content, object? options) result<*originchats.Message, error>

send posts content (text, may be "") and returns the sent message. Options: embeds (array of embeds or objects), attachments (array of objects from client.upload), alias ({name, avatar, color}: post under another name), replyTo (message id), ping (boolean, default true: notify the replied-to author). Signed when the client is signing.

#channel.sendAs(string name, string content, any ...extra) *originchats.Message

Deprecated. Deprecated: use channel.send(content, {alias: {name, avatar, color}}) instead.

sendAs posts under another name: sendAs(name, content, avatar?, color?).

#channel.sendAttachment(string content, object attachment) *originchats.Message

Deprecated. Deprecated: use channel.send(content, {attachments: [attachment]}) instead.

sendAttachment posts content with an attachment.

#channel.sendEmbed(string content, *originchats.Embed embed) *originchats.Message

Deprecated. Deprecated: use channel.send(content, {embeds: [embed]}) instead.

sendEmbed posts content with an embed.

#channel.sendWith(object payload) *originchats.Message

Deprecated. Deprecated: use channel.send(content, options) instead.

sendWith posts a raw payload here.

#channel.threadID() string?

threadID is the thread id, or null for a channel.

#channel.threads(any ...limit) array

Deprecated. Deprecated: use channel.listThreads({limit}) instead.

threads lists the channel's threads: threads(limit?).

#channel.typing() result<unit, error>

typing shows the bot as typing here for a few seconds.

#channel.unpin(string id) boolean

Deprecated. Deprecated: use message.unpin() instead.

unpin unpins the message id.

#channel.unpinThread() result<unit, error>

unpinThread unpins the thread. Throws StateError on a channel handle.

#channel.unreact(string id, string emoji) boolean

Deprecated. Deprecated: use message.unreact(emoji) instead.

unreact removes a reaction from the message id.

#channel.webhooks() result<array, error>

webhooks returns the channel's webhooks.

`*originchats.Message`

#message.alias() any

alias is the {name, avatar, usercolor} the message was posted under, or null.

#message.arg(int index) string?

arg is the index-th word of content (1 for the first), or null when there are fewer words.

#message.args() array

args splits content on whitespace, handy inside prefix commands.

#message.authorID() string

authorID is the author's rotur user id ("" when the server didn't send one).

#message.channel() string

channel is the name of the channel the message is in.

#message.client() *originchats.Client

client is the client that received or sent the message.

#message.content() string

content is the message text. Inside a prefix command it is the text after the prefix.

#message.data() object

data is the message object as the server sent it.

#message.delete() result<unit, error>

delete deletes the message.

#message.edit(string content, object? options) result<unit, error>

edit replaces the message's text. Options: embeds, attachments (as for channel.send). Only the bot's own messages can be edited.

#message.editWith(object payload) boolean

Deprecated. Deprecated: use message.edit(content, options) instead.

editWith edits the message with a raw payload.

#message.embeds() array

embeds lists the message's embed objects.

#message.id() string

id is the message id.

#message.interaction() any

interaction is the slash command call the message answers, or null.

#message.isAutomated() boolean

isAutomated reports whether a webhook or slash command posted the message.

#message.isEdited() boolean

isEdited reports whether the message was edited.

#message.isEphemeral() boolean

isEphemeral reports whether only the bot can see the message.

#message.isPinned() boolean

isPinned reports whether the message is pinned.

#message.isReply() boolean

isReply reports whether the message replies to another.

#message.isSigned() boolean

isSigned reports whether the message carries a rotur signature (verify checks it).

#message.isThread() boolean

isThread reports whether the message is in a thread.

#message.mentions(string name) boolean

mentions reports whether the message pings name or contains @name (ignoring case).

#message.mentionsMe() boolean

mentionsMe reports whether the message mentions the bot.

#message.pin() result<unit, error>

pin pins the message.

#message.pings() object

pings is the message's mentions as {users, roles, replies}.

#message.poll() any

poll is the poll in the message's embeds ({question, options, ...}), or null.

#message.raw() object

raw is the whole server packet the message arrived in.

#message.react(string emoji) result<unit, error>

react adds the reaction emoji.

#message.reactions() object

reactions is an object of emoji to the usernames who reacted.

#message.replies() result<array, error>

replies returns the replies to the message as objects.

#message.reply(string content, object? options) result<*originchats.Message, error>

reply replies to the message in its channel or thread and returns the reply. Options: ping (boolean, default true: notify the author), embeds, attachments, alias (as for channel.send).

#message.replyEmbed(string content, *originchats.Embed embed) *originchats.Message

Deprecated. Deprecated: use message.reply(content, {embeds: [embed]}) instead.

replyEmbed replies with content and an embed.

#message.replyNoPing(string content) *originchats.Message

Deprecated. Deprecated: use message.reply(content, {ping: false}) instead.

replyNoPing replies without notifying the author.

#message.replyTo() any

replyTo is the replied-to message summary ({id, user, ...}), or null.

#message.replyWith(object payload) *originchats.Message

Deprecated. Deprecated: use message.reply(content, options) instead.

replyWith replies with a raw payload.

#message.send(string content) *originchats.Message

Deprecated. Deprecated: use message.target().send(content) instead.

send posts content in the message's channel.

#message.sendEmbed(string content, *originchats.Embed embed) *originchats.Message

Deprecated. Deprecated: use message.target().send(content, {embeds: [embed]}) instead.

sendEmbed posts content with an embed in the message's channel.

#message.sendWith(object payload) *originchats.Message

Deprecated. Deprecated: use message.target().send(content, options) instead.

sendWith posts a raw payload in the message's channel.

#message.sentAt() number

sentAt is when the message was sent, in unix ms.

#message.target() *originchats.Channel

target is a handle for the channel or thread the message is in.

#message.threadID() string?

threadID is the thread the message is in, or null outside threads.

#message.timestamp() number

Deprecated. Deprecated: use message.sentAt() instead, which is in unix ms.

timestamp is when the message was sent, in unix seconds.

#message.typing()

Deprecated. Deprecated: use message.target().typing() instead.

typing shows typing in the message's channel.

#message.unpin() result<unit, error>

unpin unpins the message.

#message.unreact(string emoji) result<unit, error>

unreact removes the bot's reaction emoji.

#message.user() string

user is the author's username.

#message.verify() result<boolean, error>

verify reports whether the message's rotur signature is valid for its author. Unsigned messages, signatures more than 5 minutes off the message time and unknown keys are false. Fails only when the author's key can't be fetched (NetworkError and the like).

#message.verifyEmbeds() result<boolean, error>

verifyEmbeds reports whether the message has embeds and every one carries a valid author signature. Fails like verify.

#message.webhook() any

webhook is the webhook that posted the message, or null.

`*originchats.Slash`

#slash.arg(string name) any

arg is the argument called name, or null when it wasn't given.

#slash.argBool(string name) boolean

argBool is the argument called name as a boolean, false when it wasn't given (see has).

#slash.argNum(string name) number

argNum is the argument called name as a number, 0 when it wasn't given (see has).

#slash.argStr(string name) string

argStr is the argument called name as text, "" when it wasn't given (see has).

#slash.args() object

args is an object of every argument given, by input name.

#slash.channel() string

channel is the channel name the command was called in.

#slash.client() *originchats.Client

client is the client the command was called on.

#slash.command() string

command is the command name, without "/".

#slash.has(string name) boolean

has reports whether the argument called name was given.

#slash.id() string

id is the call id.

#slash.invoker() string

invoker is the caller's user id.

#slash.isEphemeral() boolean

isEphemeral reports whether only the caller sees the response.

#slash.isSigned() boolean

isSigned reports whether the call carries the caller's rotur signature.

#slash.raw() object

raw is the whole slash_call packet.

#slash.respond(string text) result<unit, error>

respond answers the call with text (signed when the client is signing). Fails with StateError when the client isn't connected.

#slash.send(string content) *originchats.Message

Deprecated. Deprecated: use call.target().send(content) instead.

send posts content in the command's channel.

#slash.sendEmbed(string content, *originchats.Embed embed) *originchats.Message

Deprecated. Deprecated: use call.target().send(content, {embeds: [embed]}) instead.

sendEmbed posts content with an embed in the command's channel.

#slash.target() *originchats.Channel

target is a handle for the channel or thread the command was called in.

#slash.threadID() string?

threadID is the thread the command was called in, or null.

#slash.user() string

user is the caller's username (the id when the server sent no username).

#slash.verify() result<boolean, error>

verify reports whether the call's rotur signature is valid for the caller. Unsigned calls and unknown keys are false. Fails only when the caller's key can't be fetched.

`*originchats.SlashCommand`

#slashCommand.addBoolean(string name, object? options) *originchats.SlashCommand

addBoolean adds a true/false input; it mutates the command and returns it. Options as for addString.

#slashCommand.addChoice(string name, array choices, any ...extra) *originchats.SlashCommand

Deprecated. Deprecated: use slashCommand.addChoices(name, choices, {description, required}) instead.

addChoice adds an enum input in place: addChoice(name, choices, description?, required?).

#slashCommand.addChoices(string name, array choices, object? options) *originchats.SlashCommand

addChoices adds an input limited to choices (strings); it mutates the command and returns it. Options as for addString.

#slashCommand.addInput(any kind, string name, any ...extra) *originchats.SlashCommand

Deprecated. Deprecated: use slashCommand.addString, addInteger, addNumber, addBoolean or addUser instead.

addInput adds an input of kind ("str", "int", "float", "bool", "user" or "enum") in place: addInput(kind, name, description?, required?).

#slashCommand.addInteger(string name, object? options) *originchats.SlashCommand

addInteger adds a whole-number input; it mutates the command and returns it. Options as for addString.

#slashCommand.addNumber(string name, object? options) *originchats.SlashCommand

addNumber adds a number input; it mutates the command and returns it. Options as for addString.

#slashCommand.addOption(object option) *originchats.SlashCommand

addOption adds a raw option object in the server's format; it mutates the command and returns it.

#slashCommand.addString(string name, object? options) *originchats.SlashCommand

addString adds a text input called name; it mutates the command and returns it. Options: description (string, default name), required (boolean, default true).

#slashCommand.addUser(string name, object? options) *originchats.SlashCommand

addUser adds a user input; it mutates the command and returns it. Options as for addString.

#slashCommand.blacklistRoles(array roles) *originchats.SlashCommand

blacklistRoles stops members with one of roles using the command; it mutates the command and returns it.

#slashCommand.description(string text) *originchats.SlashCommand

description sets the command's description; it mutates the command and returns it.

#slashCommand.ephemeral(boolean on) *originchats.SlashCommand

ephemeral makes responses visible only to the caller (on true); it mutates the command and returns it.

#slashCommand.fn(any handler)

fn registers the command with handler(call); see client.slash.

#slashCommand.whitelistRoles(array roles) *originchats.SlashCommand

whitelistRoles lets only members with one of roles use the command; it mutates the command and returns it.

`*originchats.Embed`

#embed.addField(string name, string value, object? options) *originchats.Embed

addField adds a name/value field; it mutates the embed and returns it. Options: inline (boolean, show next to other inline fields).

#embed.asPoll(string question, array choices, object? options) *originchats.Embed

asPoll turns the embed into a poll asking question; it mutates the embed and returns it. choices are strings or {text, emoji} objects. Options: multiselect (boolean).

#embed.audio(string link) *originchats.Embed

audio sets audio from link; it mutates the embed and returns it.

#embed.author(string name, any ...extra) *originchats.Embed

Deprecated. Deprecated: use embed.withAuthor(name, {url, iconURL}) instead.

author sets the author line in place: author(name, url?, iconURL?).

#embed.build() object

build returns the embed as the object the server receives.

#embed.color(any value) *originchats.Embed

color sets the accent color value: "#rrggbb", {r, g, b} or a 0xRRGGBB number; it mutates the embed and returns it. Throws ValueError for a malformed color.

#embed.description(string text) *originchats.Embed

description sets the description; it mutates the embed and returns it.

#embed.field(string name, string value, any ...inline) *originchats.Embed

Deprecated. Deprecated: use embed.addField(name, value, {inline}) instead.

field adds a field in place: field(name, value, inline?).

#embed.image(string link) *originchats.Embed

image sets a large image from link; it mutates the embed and returns it.

#embed.markdown(boolean on) *originchats.Embed

markdown turns markdown rendering on (true) or off; it mutates the embed and returns it.

#embed.poll(string question, array choices, any ...multiselect) *originchats.Embed

Deprecated. Deprecated: use embed.asPoll(question, choices, {multiselect}) instead.

poll turns the embed into a poll in place: poll(question, options, multiselect?).

#embed.thumbnail(string link) *originchats.Embed

thumbnail sets a small image from link; it mutates the embed and returns it.

#embed.timestamp(string value) *originchats.Embed

timestamp shows value, an ISO 8601 time; it mutates the embed and returns it.

#embed.title(string text) *originchats.Embed

title sets the title; it mutates the embed and returns it.

#embed.url(string link) *originchats.Embed

url makes the title link to link; it mutates the embed and returns it.

#embed.video(string link) *originchats.Embed

video sets a video from link; it mutates the embed and returns it.

#embed.withAuthor(string name, object? options) *originchats.Embed

withAuthor sets the author line; it mutates the embed and returns it. Options: url (string), iconURL (string).

#embed.withFooter(string text, object? options) *originchats.Embed

withFooter sets the footer line; it mutates the embed and returns it. Options: iconURL (string).

Edit this page View as Markdown