The "/chat-poll" page:

The chat page generated by /chat using an XHR to this page to request new chat content. A typical invocation is:

/chat-poll/N
/chat-poll?name=N

The "name" argument should begin with an integer which is the largest "msgid" that the chat page currently holds. If newer content is available, this routine returns that content straight away. If no new content is available, this webpage blocks until the new content becomes available. In this way, the system implements "hanging-GET" or "long-poll" style event notification. If no new content arrives after a delay of approximately chat-poll-timeout seconds (default: 420), then reply is sent with an empty "msg": field.

If N is negative, then the return value is the N most recent messages. Hence a request like /chat-poll/-100 can be used to initialize a new chat session to just the most recent messages.

Some webservers (althttpd) do not allow a term of the URL path to begin with "-". Then /chat-poll/-100 cannot be used. Instead you have to say "/chat-poll?name=-100".

If the integer parameter "before" is passed in, it is assumed that the client is requesting older messages, up to (but not including) that message ID, in which case the next-oldest "n" messages (default=chat-initial-history setting, equivalent to n=0) are returned (negative n fetches all older entries). The client then needs to take care to inject them at the end of the history rather than the same place new messages go.

If "before" is provided, "name" is ignored.

The reply from this webpage is JSON that describes the new content. Format of the json:

    {
      "msgs":[
        {
           "msgid": integer // message id
           "mtime": text    // When sent:  YYYY-MM-DD HH:MM:SS UTC
           "lmtime: text    // Localtime where the message was sent from
           "xfrom": text    // Login name of sender
           "uclr":  text    // Color string associated with the user
           "xmsg":  text    // HTML text of the message
           "fsize": integer // file attachment size in bytes
           "fname": text    // Name of file attachment
           "fmime": text    // MIME-type of file attachment
           "mdel":  integer // message id of prior message to delete
        }
      ]
    }

The "fname" and "fmime" fields are only present if "fsize" is greater than zero. The "xmsg" field may be an empty string if "fsize" is zero.

The "msgid" values will be in increasing order.

The "mdel" will only exist if "xmsg" is an empty string and "fsize" is zero.

The "lmtime" value might be unknown, in which case it is omitted.

The messages are ordered oldest first unless "before" is provided, in which case they are sorted newest first (to facilitate the client-side UI update).

As a special case, if this routine encounters an error, e.g. the user's permissions cannot be verified because their login cookie expired, the request returns a slightly modified structure:

    {
      "msgs":[
        {
          "isError": true,
          "xfrom": null,
          "xmsg": "error details"
          "mtime": as above,
          "ltime": same as mtime
        }
      ]
    }

If the client gets such a response, it should display the message in a prominent manner and then stop polling for new messages.