Chatbot

API commands.

Power-user territory. Wire a command to an external API and pull a live value into the reply: a weather report, a count from your own service, a fact from a public endpoint. If you are not comfortable with APIs, you can safely skip this page.

Advanced feature

This page is for people comfortable calling web APIs. Everything else in the chatbot works without it. If a third party offers a simple URL that returns data, you can surface it in chat here.

The idea

An API command calls a URL when the command runs, then drops the result into the response with the $(api) token. Turn on API call on a command and fill in the request.

Field	What it is
API URL	The address to call. Can contain variables, e.g. `$(querystring)` for viewer input.
Method	GET (read, the usual choice), or POST / PUT when an API needs data sent to it.
Response type	JSON (pull a single field by path) or Text (use the whole body as-is).
Field path	For JSON: a dotted path to the value you want, e.g. main.temp.
Authentication	Optional. Bearer token, a custom header, or a query parameter.

api command GET + auth Live

Viewer types

ferret_king: !weather Tokyo

Request

GETapi.weatherapi.com/v1/current.json?q=$(querystring)

Authorization: Bearer ••••4f9a

JSON response · field path current.temp_c

{ "location": { "name": "Tokyo" }, "current": { "temp_c": 18.2, "humidity": 64 } }

Bot replies · $(api) resolved

BOTOverlayThingTokyo it is 18.2°C right now

Reading the response

How you read the result depends on the response type:

Text: $(api) is the whole response body, cleaned to a single line.
JSON with a field path: $(api) is the value at your configured path.
JSON, ad-hoc field: $(api.some.field) pulls any field by path, even array indexes like $(api.results.0.name).

A dotted path

A JSON path walks into the response object. If the API returns { "main": { "temp": 21 } }, the path main.temp gives 21. A missing path just renders empty.

Failures stay silent

If a call fails or returns something odd, $(api) renders empty rather than posting an error: a non-2xx status (404, 500, …), an unreachable host or timeout, unparseable JSON, or a missing field all yield nothing. Any HTML body is dropped (chat is plain text), and an over-long value is trimmed so it can't blow past Twitch's message limit. The rest of your reply still sends with the blank filled in.

Using viewer input safely

To let a viewer pass an argument into the URL, use $(querystring), which URL-encodes whatever they typed. Never use the raw $(query) in a URL: a space or symbol would break the request, and unescaped input is a risk.

Worked example: a weather command

A viewer types !weather London and gets the temperature back.

!weatherGET · JSON

API URL:      https://api.example.com/weather?q=$(querystring)
Response:     JSON
Field path:   current.temp_c
Response text: $(touser) it is $(api)°C right now

Worked example: a value from your own service

Suppose you run a small service that returns plain text, like a current giveaway count.

!playersGET · Text

API URL:      https://api.example.com/players/online
Response:     Text
Response text: Players online right now: $(api)

Authentication

When an API needs a key, choose a scheme and paste the secret. The secret is encrypted at rest and never shown back to you or posted in chat.

Scheme	How the secret is sent
Bearer	As an `Authorization: Bearer …` header.
Header	As a custom request header whose name you set.
Query	As a query parameter appended to the URL.

Safe by design

Responses are fetched server-side with protection against pointing a command at internal addresses, capped to a single clean line, and briefly cached so a command on a short cooldown does not hammer the third party. If a call fails, the token just renders empty rather than leaking an error into chat.