HTTP Responses (res)¶

Your webhook and webapp's voice — send JSON, HTML, redirects, and rendered templates back to whoever called your endpoint.

Once you call res, the response goes out and command execution ends. Choose wisely.

What is `res`?¶

The res instance sends custom HTTP responses from webhook and webapp commands. Use it to build JSON APIs, HTML pages, redirects, and rendered templates.

You get	You skip
Chainable methods (`res.status().json()`)	Manual header management
EJS templates built in	Separate templating setup
Auto-detected content types	Guessing MIME types

Once a response is sent, command execution ends.

How to use it¶

Drop this in a webhook or webapp command's Logic field:

res.status(200).json({ ok: true, data: result })

Three things worth knowing upfront:

res is only available in webhook and webapp commands — it's null in normal Telegram commands.
Methods chain — res.status(201).set("Cache-Control", "no-store").json({ ... }).
No res call? The platform returns { "status": "success" } with HTTP 200.

New to TBL?

request and params carry incoming HTTP data in webhook/webapp commands. Quick intro: Learning TBL. Endpoint setup: Webhooks · Webapps.

When `res` is available¶

Context	`res`
User webhook	Available
Global webhook	Available
Webapp command	Available
Public web (`/public/...`)	Not available — raw command code is served directly
Telegram message commands	`null`
Broadcast commands	`null`

Public web pages do not run the command sandbox, so there is no res object. See Public Web.

Try it — copy-paste examples¶

Start simple. Each example only introduces what it needs.

JSON API response¶

res.json({ ok: true, message: "Hello from your bot API" })

HTML page¶

res.html("<h1>Dashboard</h1><p>Welcome!</p>")

Chain status and headers¶

res
  .status(201)
  .set("Cache-Control", "no-store")
  .json({ created: true, id: newId })

Redirect (HTTPS only)¶

res.redirect("https://example.com/done")

Render another command as the response¶

res.render("template.html", { data: { title: "My Page", items: [] } })

Choosing a method¶

Goal	Method
REST / API JSON	`res.json()`
Plain text or logs	`res.text()`
Full HTML page	`res.html()` or `res.render("page.html")`
Reuse another command's code	`res.render("template.html", { data: { ... } })`
Send user elsewhere	`res.redirect("https://example.com/done")`
Custom headers / status	`res.set()` + `res.status()` + `res.send()`

Method overview¶

Method	Purpose	Chains?
`set(key, value)`	Set response headers	Yes
`status(code)`	Set HTTP status (default 200)	Yes
`send(body)`	Send any body (auto-detects HTML)	Yes
`json(obj)`	Send `application/json`	Yes
`text(content)`	Send `text/plain` (EJS if `<%` present)	Yes
`xml(content)`	Send `application/xml`	Yes
`html(content)`	Send `text/html` with EJS + injection	Yes
`redirect(url)`	HTTPS redirect only	Yes
`render(path, options)`	Render another command as the response	Yes
`renderEJS(template, data)`	Explicit EJS → HTML	Yes
`end()`	Return stored response state (advanced)	No

Unknown method names (via chaining proxy) return 404 JSON.

Method chaining¶

All response methods except end() return res, so you can chain:

res
  .status(201)
  .set("Cache-Control", "no-store")
  .json({ created: true, id: newId })

Default response¶

If your command finishes without calling res, the platform returns:

{ "status": "success" }

with HTTP 200. See Defaults & Protection.

Pages in this section¶

Headers & Status — set(), status(), end()
JSON, Text & XML — send(), json(), text(), xml()
HTML & EJS — html(), renderEJS(), template syntax
Redirects — redirect() rules
res.render() — render commands, content types, data passing
Defaults & Protection — fallbacks, HTML age-gate, injection

Webhooks — signed HTTP endpoints
Webapps — unsigned dynamic endpoints
Public Web — static is_web pages (no res)
request — incoming HTTP data in webhook/webapp commands