Fetch URL — Externe APIs ohne C¶

Streamer.bot kann externe Web-APIs aufrufen via Core → Network → Fetch URL. Damit baust du Commands die externe Daten holen (Wetter, Witze, Cat-Facts, beliebige JSON-APIs) ohne eine Zeile C#-Code.

Doku: https://docs.streamer.bot/api/sub-actions/core/network/fetch-url

Wichtige Limitation¶

Was geht	Was nicht geht
GET-Requests	POST / PUT / DELETE / PATCH
Custom Headers	Request Body
JSON-Response parsen	Basic Auth direkt im Sub-Action
Status-Code prüfen	Cookies / Sessions

Für POST/PUT/DELETE musst du C# nutzen. Wir vermeiden hier C# — also bauen wir nur GET-basierte Read-only-Integrationen.

Fetch URL Sub-Action¶

Pfad: Core → Network → Fetch URL

Feld	Bedeutung
URL	Vollständige Ziel-URL inkl. Query-Parameter (`?key=value`)
Variable Name	In welche lokale Variable die Response gespeichert wird
Parse result as JSON	Toggle (default: aus). Wenn an → JSON wird in `%<varName>.<key>%` aufgesplittet
Headers	Optional. Custom HTTP-Headers (z.B. `User-Agent`, `Accept`)

Output¶

Ohne JSON-Parsing:

Variable	Inhalt
`%<variableName>%`	Komplette Response als String

Mit JSON-Parsing (Toggle an):

Variable	Inhalt
`%<variableName>.<key>%`	Jeder Top-Level-Key wird zur Variable
`%<variableName>.<key>.<subkey>%`	Nested Keys

Beispiel: API liefert {"fact": "Katzen schlafen 16h", "length": 23}. Mit Variable Name cat:

%cat.fact% = Katzen schlafen 16h
%cat.length% = 23

Status-Code prüfen¶

Streamer.bot setzt nach Fetch URL eine Variable für den HTTP-Status. Genauer Name: %fetchUrlStatusCode% (das ist die übliche Schreibweise — Doku-Status check empfohlen wenn unklar).

Pattern für Fehler-Handling:

1. Fetch URL: https://api.example.com/data → meinResult
2. If/Else: %fetchUrlStatusCode% Greater Than 299
   ├── Send Message: "@%user% API gerade nicht erreichbar (Status %fetchUrlStatusCode%)"
   └── Break
3. Send Message: "@%user% Antwort: %meinResult%"

JSON-Parsing Beispiel¶

API: https://catfact.ninja/fact liefert:

{
  "fact": "A cat's normal pulse is 140-240 beats per minute.",
  "length": 51
}

Sub-Action:

Feld	Wert
URL	`https://catfact.ninja/fact`
Variable Name	`cat`
Parse result as JSON	✅ aktiv

Danach: - %cat.fact% = A cat's normal pulse is 140-240 beats per minute. - %cat.length% = 51

Nested-JSON¶

API liefert:

{
  "user": {
    "name": "Bob",
    "age": 30
  },
  "status": "ok"
}

Mit Variable Name data: - %data.user.name% = Bob - %data.user.age% = 30 - %data.status% = ok

Arrays in JSON¶

API: {"jokes": [{"text": "Joke 1"}, {"text": "Joke 2"}]} — Index-Zugriff: %data.jokes[0].text% oder %data.jokes.0.text% (Syntax kann je nach SB-Version variieren).

Pragmatisch: Wenn die API ein Array zurückgibt, lieber eine API die einen einzelnen Eintrag liefert nutzen. Macht das Pattern einfacher.

URL-Encoding¶

Wenn User-Input in die URL muss (z.B. !weather München), brauchst du URL-Encoding:

%input0% → München
Für URL: München muss zu M%C3%BCnchen (URL-encoded)

Streamer.bot hat dafür Variablen: %input0URLEncoded% (in Command Triggered Trigger) ODER Inline Function $urlencode(text)$ .

Beispiel:

URL: https://wttr.in/$urlencode(%rawInput%)$?format=3

Custom Headers¶

User-Agent setzen ist oft sinnvoll (manche APIs blocken Default-Agents):

Header	Wert
`User-Agent`	`AzaCraft Streamer.bot/1.0`
`Accept`	`application/json`

Manche APIs verlangen API-Key per Header (z.B. X-API-Key: dein-key). Kein Problem — einfach im Headers-Feld eintragen.

API-Key per Query-Parameter¶

Wenn API-Key in URL geht (z.B. OpenWeatherMap): einfach in URL hardcoden oder per Argument einsetzen:

URL: https://api.openweathermap.org/data/2.5/weather?q=%input0%&appid=DEIN_KEY_HIER

Security-Tipp: Wenn dein API-Key sensitiv ist, in Persisted Global ablegen statt hartkodieren: 1. Global (Set) weatherApiKey = "abc123" (einmalig manuell) 2. In URL: &appid=~weatherApiKey~

So ist der Key nicht in der Action-Definition selbst.

API-Use-Cases in dieser Sektion¶

Command	MD	API
`!weather <stadt>`	weather.md	wttr.in (kostenlos, kein Key)
`!joke`	joke.md	official-joke-api oder icanhazdadjoke
`!catfact`	catfact.md	catfact.ninja (kostenlos)

Häufige Fallen¶

POST/PUT in Fetch URL versuchen — geht nicht, nur GET. Doku lesen oder C# nutzen
API-Rate-Limit — kostenlose APIs haben oft Limits (z.B. 1000/Tag). Mit Cooldown im Command zähmen
CORS — irrelevant für Streamer.bot (keine Browser-Anfrage)
HTTPS-Zertifikat — selten Probleme. Bei Fail: API per Browser-curl prüfen
JSON-Parse-Toggle vergessen — ohne den Toggle ist %var% der Raw-String. Mit Toggle wird's gesplittet
Sehr lange Responses — Twitch-Chat hat 500-Zeichen-Limit. Bei langem JSON evtl. nur Teilfeld nutzen, nicht die ganze Response

Quellen¶

Fetch URL: https://docs.streamer.bot/api/sub-actions/core/network/fetch-url