:orphan:

.. _rest:

Longpoll JSON event feed
------------------------

Steps:

1. Load the room event feed :code:`:events_api_url:/:username/:token/` (displayed on user's settings page on CB)
2. You will receive a list of all latest events plus `nextUrl`.
3. Use `nextUrl` to load the next set of events, and continue like this for as long as you want.

Optional query parameter

* timeout: The server will wait at most this long before returning results.
  If a timeout is not set, the `nextUrl` will default to a 10 second timeout

  * example: :code:`:events_api_url:/:username/:token/?timeout=0`
  * default: 10
  * min: 0
  * max: 90

.. container:: toggle

    .. container:: header

        Example code

    .. code-block:: javascript

        const baseUrl = ":events_api_url:/testuser/************************/"
        function getEvents(url) {
            fetch(url).then(response => response.json())
            .then(jsonResponse => {
                // Process messages
                for (const message of jsonResponse["events"]) {
                    const method = message["method"]
                    const object = message["object"]
                    console.log(`Message ID: ${message["id"]}`)
                    if (method === "broadcastStart") {
                        console.log("Broadcast started")
                    } else if (method === "broadcastStop") {
                        console.log("Broadcast stopped")
                    } else if (method === "userEnter") {
                        console.log(`${object["user"]["username"]} entered the room`)
                    } else if (method === "userLeave") {
                        console.log(`${object["user"]["username"]} left the room`)
                    } else if (method === "follow") {
                        console.log(`${object["user"]["username"]} has followed`)
                    } else if (method === "unfollow") {
                        console.log(`${object["user"]["username"]} has unfollowed`)
                    } else if (method === "fanclubJoin") {
                        console.log(`${object["user"]["username"]} joined the fan club`)
                    } else if (method === "chatMessage") {
                        console.log(`${object["user"]["username"]} sent chat message: ${object["message"]["message"]}`)
                    } else if (method === "privateMessage") {
                        console.log(`${object["message"]["fromUser"]} sent private message to ${object["message"]["toUser"]}: ${object["message"]["message"]}`)
                    } else if (method === "tip") {
                        console.log(`${object["user"]["username"]} sent ${object["tip"]["tokens"]} tokens ${object["tip"]["isAnon"] ? "anonymously" : ""} ${object["tip"]["message"] ? `with message: ${object["tip"]["message"]}` : ""}`)
                    } else if (method === "roomSubjectChange") {
                        console.log(`Room Subject changed to ${object["subject"]}`)
                    } else if (method === "mediaPurchase") {
                        console.log(`${object["user"]["username"]} purchased ${object["media"]["type"]} set: ${object["media"]["name"]}`)
                    } else {
                        console.error("Unknown method:", method)
                    }
                }

                // Once messages are processed, call getEvents again with 'nextUrl' to get new messages
                getEvents(jsonResponse["nextUrl"])
            })
            .catch(err => {
                console.error("Error:", err)
            })
        }

        getEvents(baseUrl)

.. note::
    The rate limit for the API is 2000 requests per minute.

Example Response
----------------
The response is a json encoded string that needs to be deserialized.

.. code-block:: text

    {
      "events": [
        {
            "method": "chatMessage",
            "id": "1625274862454-0",
            "object": {...}
        }
      ],
      "nextUrl": ":events_api_url:/testuser/************************/?i=1625274862454-0&timeout=10",
    }

* ``events``: an array that may contain zero or more items
* ``nextUrl``: the URL you should extract and load to listen for subsequent events

| ``id`` refers to the unique ID of an event.
| ``object`` field varies depending on ``method``, please check :ref:`index:Method Types`.