Skip to content
TipPage Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

{urlfetch:https://…}

Replace the variable with whatever text a URL returns, or one field of a JSON response.

{urlfetch:https://example.com/anything}
{urlfetch:https://example.com/anything|field}

Platforms: Twitch and Kick.

The bot fetches the address and drops the response text into the message - perfect for pulling live data from your own server or a third-party API into a chat response.

Examples

!weather  →  {urlfetch:https://wttr.in/London?format=3}
!define   →  {urlfetch:https://api.example.com/define?word={queryescape:{arg:1}}}

The second one is the pattern for viewer input: the address is yours, fixed when you save the command, and the viewer’s word rides in the query, encoded by {queryescape:}.

Reading one field from JSON

Most public APIs answer with JSON rather than plain text - posting that raw would put {"fact":"...","length":61} in chat. Put | and the field’s name after the address and the bot posts just that field:

!catfact  →  {urlfetch:https://catfact.ninja/fact|fact}
!advice   →  {urlfetch:https://api.adviceslip.com/advice|slip.advice}
!chuck    →  {urlfetch:https://api.chucknorris.io/jokes/random|value}
!fact     →  {urlfetch:https://uselessfacts.jsph.pl/api/v2/facts/random|text}
!8ball    →  {urlfetch:https://yesno.wtf/api|answer}
  • Dots go deeper. adviceslip answers {"slip": {"id": 42, "advice": "..."}}, so the advice is slip.advice.
  • Numbers pick from a list, counting from 0: |0.q is the q of the first item, and |data.0.text (or |data[0].text) the text of the first item in data.
  • To find the field, open the address in your browser - most browsers lay JSON out so you can read the names off.
  • The field has to be written out - no variables in it. Numbers and true/false come out as text; an empty field leaves the variable empty.

Two fields, one message. Two {urlfetch:} with the same address in one reply read the same fetch, so a two-part joke stays one joke (the next time the command runs, it fetches a new one):

{urlfetch:https://official-joke-api.appspot.com/random_joke|setup} ... {urlfetch:https://official-joke-api.appspot.com/random_joke|punchline}

If the address itself contains a |, write it as %7C - otherwise everything after it is read as a field name.

Good to know

  • The host is fixed. Variables may appear in the path or query, never in the domain - a viewer can never steer the fetch somewhere else. Close the host with a / or ? before the first variable (https://api.example.com/{args}, not https://api.example.com{args}).
  • Requests go out from a CDN edge (Cloudflare’s network), not from TipPage’s own servers - the endpoint you call sees a Cloudflare edge IP. Allow Cloudflare’s ranges or use a token in your URL rather than allowlisting one address.
  • HTTPS only, and responses are trimmed to plain text and capped to fit a chat message (about 400 characters). The bot reads up to 32 KB of the response, so a JSON field can sit anywhere in a normal API answer.
  • Every use fetches fresh - nothing is cached, so a random-fact command gives a new fact each time. Use the command’s cooldown to keep a spammed command from hammering the site.
  • Whatever comes back is treated as text - a response containing {variables} is shown literally, not run.
  • Up to two {urlfetch:} per response. Available to Twitch partners, and to everyone once the edge relay is enabled for your account.
  • A failed fetch leaves the variable empty and the rest of the message still posts. Open the command’s editor to see why the last fetch failed - a timeout (over 2 seconds), an error status from the site, a redirect (use the final address), the site’s own bot protection blocking the request, or a JSON field that isn’t there (the editor lists the fields the response does have).
  • Some sites block it. Sites behind Cloudflare’s bot protection often challenge requests coming from Cloudflare’s network, and there is nothing TipPage can do about that from our side - use an API meant for programs, or one you run yourself.

If you run the endpoint

Every request the bot makes identifies itself, so you can tell it apart from other traffic and know who to talk to if a command is misbehaving:

User-Agent: TipPage-Urlfetch/1.0 (+https://docs.tippage.com/chat-bot/variables/urlfetch)
X-TipPage-Tenant: t_3501414b

X-TipPage-Tenant is the id of the TipPage channel whose command made the request. To report a command that’s hammering or misusing your service, email hello@tippage.com with that id and we’ll take it from there. You can also simply refuse requests carrying it - the streamer’s command will render an empty result.

Was this page helpful?