$(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.

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.

Name	Value
`x-fossabot-channelid`	The internal Fossabot ID of a broadcaster.
`x-fossabot-channeldisplayname`	The uppercase version, or internationalized version of a broadcaster’s username.
`x-fossabot-channellogin`	The lowercase version of a broadcaster’s username (otherwise known as login).
`x-fossabot-channelslug`	The Fossabot channel URL of a broadcaster. Useful for linking to commands pages.
`x-fossabot-channelprovider`	The platform the request was sent from (e.g. `twitch`).
`x-fossabot-channelproviderid`	The platform ID (e.g. the Twitch ID) of a broadcaster.
`x-fossabot-customapitoken`	The token that uniquely identifies this request. Use this with our API endpoints.
`x-fossabot-hasmessage`	`true` or `false` depending on whether a message triggered this request (`false` if timer, etc).
`x-fossabot-validateurl`	Refer to Validating requests for more information about this endpoint.
`user-agent`	`Fossabot Web Proxy`

List of Message Headers

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

Name	Value
`x-fossabot-message-id`	The message ID from the provider (e.g. Twitch).
`x-fossabot-message-userlogin`	The lowercase version of the sender’s username (otherwise known as login).
`x-fossabot-message-userdisplayname`	The uppercase version, or internationalized version of the sender’s username.
`x-fossabot-message-userprovider`	The 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-userproviderid`	The 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 fieldIn 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:

Name	Value
`x-ratelimit-total`	The total size of your rate limit bucket.
`x-ratelimit-remaining`	The remaining requests in your bucket.
`x-ratelimit-reset`	A unix timestamp of when your bucket is completely refilled.

Variables

Message & Arguments

Channel & Stream

Emotes

Counters & Time

Utilities

Integrations

Parameters

Example Output

Error Output

Developers

IP Ranges

List of Common Headers

List of Message Headers

API Endpoints

Validating requests

Valid token

Invalid token

Getting context

Valid token

Invalid token

Rate Limits

​Parameters

​Example Output

​Error Output

​Developers

​IP Ranges

​List of Common Headers

​List of Message Headers

​API Endpoints

​Validating requests

Valid token

Invalid token

​Getting context

​Valid token

Invalid token

​Rate Limits

Parameters

Example Output

Error Output

Developers

IP Ranges

List of Common Headers

List of Message Headers

API Endpoints

Validating requests

Getting context

Valid token

Rate Limits