HttpRequest — Async HTTP Calls from sb0t Scripts

sb0t scripts can make outbound HTTP requests using the constructable HttpRequest object, enabling scripts to call external APIs, fetch data feeds, post webhook notifications, or retrieve content from the web. Requests run on a background thread and invoke a callback when the response arrives.

HTTP requests are asynchronous. The download() call returns immediately and the response is not available until the oncomplete callback fires. Do not attempt to read the result synchronously after calling download().

Responses are enqueued and the oncomplete callback is invoked on the main server processing thread, so callback code runs safely alongside other script events. However, particularly slow or hung remote servers may cause the background thread to linger — keep external dependencies reliable.

Creating an HttpRequest

Use new HttpRequest() to create an instance, configure its properties, and call download() to begin the request.

var req = new HttpRequest();
req.src = "https://example.com/api/data";
req.method = "GET";
req.oncomplete = function(result) {
    room.say("Response: " + result.page);
};
req.download();

HttpRequest Instance Properties

src

string

The full URL of the request target (e.g. "https://example.com/api/endpoint").

method

string

The HTTP method to use. Accepted values (case-insensitive): "GET" or "POST". Defaults to "get".

params

string

The POST body payload. Only sent when method is "POST". Encoded using UTF-8 if utf is true, otherwise using the system default encoding. The Content-Type is set to application/x-www-form-urlencoded automatically.

string

Sets the HTTP Accept request header (e.g. "application/json"). Optional.

userAgent

string

Sets the User-Agent request header. Defaults to an empty string.

host

string

Overrides the HTTP Host header. Optional — leave unset to use the host derived from src.

utf

boolean

When true, the POST body (params) is encoded as UTF-8 and the response body is decoded as UTF-8. When false, the system default encoding is used. Defaults to false.

oncomplete

function

The callback function invoked when the request completes. Receives a single HttpRequestResult argument. Set this before calling download().

HttpRequest Instance Methods

`request.header(key, value)`

Sets a custom HTTP request header. Call this before download(). Can be called multiple times for multiple headers.

key

string

required

The header name (e.g. "Authorization").

value

string

required

The header value (e.g. "Bearer my-token").

Returns: boolean — true if the header was set, false if either argument is undefined.

`request.download(arg?)`

Initiates the HTTP request on a background thread. The instance can only process one request at a time — calling download() while a request is in progress returns false immediately.

arg

string

An optional arbitrary string passed through to the HttpRequestResult.arg property in the callback. Useful for identifying which request triggered the callback when sharing one handler across multiple requests.

Returns: boolean — true if the request was started, false if the instance is already busy.

HttpRequestResult Object

The oncomplete callback receives an HttpRequestResult object as its sole argument:

page

string

The full response body as a string. Decoded using UTF-8 if utf was true on the request, otherwise using the system default encoding. Empty string if the request failed.

arg

string

The optional argument string passed to download(). Useful for correlating responses to specific requests.

Examples

var req = new HttpRequest();
req.src = "https://api.example.com/greeting";
req.method = "GET";
req.utf = true;
req.oncomplete = function(result) {
    if (result.page) {
        room.say("API says: " + result.page);
    } else {
        room.say("Request failed or returned empty.");
    }
};
req.download();

XmlParser — XML Document Object

XmlParser is a constructable object for loading and navigating XML documents. Use it to parse the response body returned by HttpRequest into a traversable node tree. It wraps the .NET XmlDocument API and surfaces Node, NodeCollection, and NodeAttributes objects.

Creating an XmlParser

var parser = new XmlParser();

XmlParser Instance Properties

available

boolean

true if an XML document has been successfully loaded or created and is ready to traverse. false before load() or create() is called, or after a failed parse.

xml

string

Returns the current XML document as a formatted (indented) UTF-8 string. Returns null if available is false or serialization fails.

nodeName

string

The name of the document root node. Returns null if available is false.

nodeValue

string

The inner text content of the entire document. Assignable. Returns null if available is false.

parentNode

Node

The parent Node of the document root, or null if there is none.

childNodes

NodeCollection

A NodeCollection of the document’s top-level child elements. Returns null if there are none or if available is false.

attributes

NodeAttributes

A NodeAttributes collection for the document root’s XML attributes. Returns null if unavailable.

XmlParser Instance Methods

`parser.load(xmlString)`

Parses an XML string and makes the document available for traversal.

xmlString

string

required

A valid XML string to parse.

Returns: boolean — true on success, false if parsing fails.

`parser.create(rootTagName)`

Creates a new empty XML document with a single root element and an XML declaration.

rootTagName

string

required

The tag name for the root element.

Returns: boolean — true on success.

`parser.getNodesByName(tagName)`

Searches the entire document for all elements with a given tag name.

tagName

string

required

The element tag name to search for.

Returns: NodeCollection — the matching nodes, or null if none were found.

`parser.appendChild(tagName)`

Creates and appends a new child element directly under the document root element.

tagName

string

required

The tag name for the new element.

Returns: Node — the newly created child node, or null on error.

`parser.removeChild(node)`

Removes a direct child Node from the document root element.

node

Node

required

The child Node instance to remove.

Returns: boolean — true on success.

Node Object

A Node represents a single XML element returned by traversal operations (childNodes, getNodesByName(), etc.).

nodeName

string

The tag name of the XML element (e.g. "item", "title").

nodeValue

string

The inner text content of the element. Can be assigned to update the node’s text in the underlying XML document.

parentNode

Node

The parent Node of this element, or null if this is the root.

childNodes

NodeCollection

A NodeCollection of child elements (excludes text/comment nodes that begin with #). Returns null if there are no child elements.

attributes

NodeAttributes

A NodeAttributes collection for this element’s XML attributes. Returns null if there are no attributes.

`node.getNodesByName(tagName)`

Searches for all descendant elements with a given tag name.

tagName

string

required

The element tag name to search for.

Returns: NodeCollection — the matching nodes, or null if none were found.

`node.appendChild(tagName)`

Creates and appends a new child element with the given tag name.

tagName

string

required

The tag name for the new element.

Returns: Node — the newly created child node, or null on error.

`node.removeChild(node)`

Removes a child Node from this node.

node

Node

required

The child Node instance to remove.

Returns: boolean — true on success.

NodeCollection Object

An array-like collection of Node objects returned by childNodes and getNodesByName().

length

number

The number of nodes in the collection. Access individual nodes by numeric index: collection[0], collection[1], etc. Comment and text nodes (whose names begin with #) are excluded automatically.

NodeAttributes Object

Returned by node.attributes and parser.attributes, this collection provides access to an element’s XML attribute names and values.

length

number

The number of attributes on the element. Access attribute names by numeric index: attrs[0], attrs[1], etc.

`attrs.getValue(name)`

name

string

required

The attribute name to look up.

Returns: string — the attribute value, or null if not found.

`attrs.setValue(name, value)`

Sets or creates an attribute on the owning element.

name

string

required

Attribute name.

value

string

required

Attribute value.

Returns: boolean — true on success.

`attrs.removeValue(name)`

Removes an attribute from the owning element.

name

string

required

The attribute name to remove.

Returns: boolean — true if removed, false if the attribute was not found.

Query Object

Query is a constructable object for building parameterized SQLite queries. It is passed to an Sql instance’s query() method for execution. The constructor accepts a SQL string with {0}, {1}, … placeholders and corresponding values:

var q = new Query("SELECT * FROM users WHERE name = {0}", "Alice");

Placeholder values may be strings, integers, or floating-point numbers. See the Sql object documentation for full database usage.

Examples

var req = new HttpRequest();
req.src = "https://feeds.example.com/rss.xml";
req.method = "GET";
req.utf = true;
req.oncomplete = function(result) {
    if (!result.page) {
        room.say("Failed to fetch feed.");
        return;
    }

    var parser = new XmlParser();

    if (!parser.load(result.page)) {
        room.say("Failed to parse XML.");
        return;
    }

    var items = parser.getNodesByName("item");

    if (!items) {
        room.say("No <item> elements found.");
        return;
    }

    for (var i = 0; i < items.length; i++) {
        var titleNodes = items[i].getNodesByName("title");
        if (titleNodes && titleNodes.length > 0) {
            room.say("Title: " + titleNodes[0].nodeValue);
        }
    }
};
req.download();

Core Objects

Utilities

HttpRequest — Async HTTP Calls from sb0t Scripts

Creating an HttpRequest

HttpRequest Instance Properties

HttpRequest Instance Methods

`request.header(key, value)`

`request.download(arg?)`

HttpRequestResult Object

Examples

XmlParser — XML Document Object

Creating an XmlParser

XmlParser Instance Properties

XmlParser Instance Methods

`parser.load(xmlString)`

`parser.create(rootTagName)`

`parser.getNodesByName(tagName)`

`parser.appendChild(tagName)`

`parser.removeChild(node)`

Node Object

`node.getNodesByName(tagName)`

`node.appendChild(tagName)`

`node.removeChild(node)`

NodeCollection Object

NodeAttributes Object

`attrs.getValue(name)`

`attrs.setValue(name, value)`

`attrs.removeValue(name)`

Query Object

Examples

Build docs developers (and LLMs) love

Core Objects

Utilities

Documentation Index

​Creating an HttpRequest

​HttpRequest Instance Properties

​HttpRequest Instance Methods

​request.header(key, value)

​request.download(arg?)

​HttpRequestResult Object

​Examples

​XmlParser — XML Document Object

​Creating an XmlParser

​XmlParser Instance Properties

​XmlParser Instance Methods

​parser.load(xmlString)

​parser.create(rootTagName)

​parser.getNodesByName(tagName)

​parser.appendChild(tagName)

​parser.removeChild(node)

​Node Object

​node.getNodesByName(tagName)

​node.appendChild(tagName)

​node.removeChild(node)

​NodeCollection Object

​NodeAttributes Object

​attrs.getValue(name)

​attrs.setValue(name, value)

​attrs.removeValue(name)

​Query Object

​Examples

Build docs developers (and LLMs) love

Creating an HttpRequest

HttpRequest Instance Properties

HttpRequest Instance Methods

`request.header(key, value)`

`request.download(arg?)`

HttpRequestResult Object

Examples

XmlParser — XML Document Object

Creating an XmlParser

XmlParser Instance Properties

XmlParser Instance Methods

`parser.load(xmlString)`

`parser.create(rootTagName)`

`parser.getNodesByName(tagName)`

`parser.appendChild(tagName)`

`parser.removeChild(node)`

Node Object

`node.getNodesByName(tagName)`

`node.appendChild(tagName)`

`node.removeChild(node)`

NodeCollection Object

NodeAttributes Object

`attrs.getValue(name)`

`attrs.setValue(name, value)`

`attrs.removeValue(name)`

Query Object

Examples