Skip to main content

$(customapi)

Returns the response of a HTTP GET request to a specified URL.

Parameters

This variable takes one required parameter that is a URL to send the HTTP GET request to.

Example Output

There is no example output as it solely depends on what the requested URL returns.

Error Output

  • In case an invalid URL is provided, or the remote server cannot be reached, returns the following:

    [Error: Failed to connect to remote server.]

Developers

All status codes will be ignored and only the raw body content of the requested URL will be returned.

Fossabot also sends multiple custom HTTP headers that you can use to build deeper integrations, a list of them can be found below.

tip

Use our API endpoints to validate whether a request originated from Fossabot, or obtain more data about the request.

IP Ranges

Fossabot's proxy does not use a consistent IP range to send requests. You cannot rely on it for authenticating endpoints!

We recommended that you use our API Endpoints to validate whether a given request actually came from Fossabot.

For that reason we do NOT print customapi URLs on public commands pages.

List of Common Headers

These headers are present in all requests.

NameValue
x-fossabot-channelidThe internal Fossabot ID of a broadcaster.
x-fossabot-channeldisplaynameThe uppercase version, or internationalized version of a broadcaster's username.
x-fossabot-channelloginThe lowercase version of a broadcaster's username (otherwise known as login).
x-fossabot-channelslugThe Fossabot channel URL of a broadcaster. Useful for linking to commands pages.
x-fossabot-channelproviderThe platform the request was sent from (e.g. twitch).
x-fossabot-channelprovideridThe platform ID (e.g. the Twitch ID) of a broadcaster.
x-fossabot-customapitokenThe token that uniquely identifies this request. Use this with our API endpoints.
x-fossabot-hasmessagetrue or false depending on whether a message triggered this request (false if timer, etc).
x-fossabot-validateurlRefer to Validating requests for more information about this endpoint.
user-agentFossabot Web Proxy

List of Message Headers

These headers are present in requests sent from messages and therefore attached to a particular user.

NameValue
x-fossabot-message-idThe message ID from the provider (e.g. Twitch).
x-fossabot-message-userloginThe lowercase version of the sender's username (otherwise known as login).
x-fossabot-message-userdisplaynameThe uppercase version, or internationalized version of the sender's username.
x-fossabot-message-userproviderThe platform the message was sent from by the user (this is useful if a Discord user toggles a Twitch command through the Discord bot, etc).
x-fossabot-message-userprovideridThe platform ID (e.g. the Twitch ID) of the sender.

API Endpoints

Fossabot exposes two API endpoints that you may use to either validate that a given customapi request originated from Fossabot, or to obtain more data that would allow you to customize how you respond to a given request.

These endpoints are rate limited.

Refer to Rate Limits for more information.

Tokens expire after 60 seconds.

You will receive a token_invalid error when sending a request to these endpoints if the token has expired.

Validating requests

This is a single use endpoint.

This means that you will only receive a valid token response the first time you call this endpoint. If you call this endpoint twice using the same token, the second request will return an error.

Fossabot exposes a single use endpoint to let you validate whether a given customapi request actually came from Fossabot.

GET https://api.fossabot.com/v2/customapi/validate/<token>
Valid token

A valid token will result in HTTP status code 200 with the following body:

{
"context_url": "https://api.fossabot.com/v2/customapi/context/<token>"
}

You may send a GET request to the value of context_url to obtain more data about the incoming request. Refer to Getting context for more information.

Invalid token

An invalid token will return HTTP status code 400 with the following body:

{
"code": "token_invalid",
"error": "Bad Request",
"message": "Invalid token",
"status": 400
}

Getting context

GET https://api.fossabot.com/v2/customapi/context/<token>

Valid token

A valid token will return HTTP status code 200 with the following body:

message is a nullable field

In the event the customapi request was dispatched from an automated action (such as a timer), message will be null.

{
"channel": {
"id": "1",
"login": "aiden",
"display_name": "Aiden",
"avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/aiden-profile_image-6d03ccc5d668cc80-300x300.jpeg",
"slug": "aiden",
"broadcaster_type": "affiliate",
"provider": "twitch",
"provider_id": "87763385",
"created_at": "2021-07-10T04:20:05.599789Z",
"stream_timestamp": "2022-09-17T19:17:27Z",
"is_live": true
},
"message": {
"id": "ae9a4e3e-d495-4d75-aec6-8965e7c4ccd0",
"content": "!testcommand",
"provider": "twitch",
"user": {
"provider_id": "87763385",
"login": "aiden",
"display_name": "Aiden",
"roles": [
{
"id": "1",
"name": "Broadcaster",
"type": "broadcaster"
},
{
"id": "3",
"name": "Moderator",
"type": "moderator"
},
{
"id": "5",
"name": "Subscriber",
"type": "subscriber"
},
{
"id": "269",
"name": "test",
"type": "custom"
},
{
"id": "14",
"name": "Admin",
"type": "custom"
}
]
}
}
}
Invalid token

An invalid token will return HTTP status code 400 with the following body:

{
"code": "token_invalid",
"error": "Bad Request",
"message": "Invalid token",
"status": 400
}

Rate Limits

Fossabot uses a leaky bucket rate limiter to protect its services from abuse. You will receive a 429 HTTP status code with the following body if you exceed the rate limit:

{
"code": "ratelimit",
"error": "Too Many Requests",
"message": "You are being rate limited.",
"status": 429
}

Rate limits may change at any time. Use the following headers to throttle your requests accordingly:

NameValue
x-ratelimit-totalThe total size of your rate limit bucket.
x-ratelimit-remainingThe remaining requests in your bucket.
x-ratelimit-resetA unix timestamp of when your bucket is completely refilled.