Skip to content

Example HTTP API Messages

Jump to bottom Edit New page
Mike Angstadt edited this page Aug 4, 2017 · 14 revisions

Authentication

Step 1: Get the fkey of the login page

Method: GET

URI: https://stackoverflow.com/users/login

Response

The response will be the HTML of the login page. The fkey is located in a hidden form field. It is a 32 character, hexadecimal value (it only contains numbers and the letters a through f).

<input type="hidden" name="fkey" value="FKEY">

Step 2: Submit credentials

Method: POST

URI: https://stackoverflow.com/users/login

Parameters:

Name Value
email The email address of the user.
password The user's password.
fkey The fkey.

Response

If an HTTP 302 response is returned, that means the login was successful. The authentication tokens are stored in cookies, just as if you were logging in from a web browser.

Getting a chat room's fkey

The "fkey" is a magical value that you need to interact with a chat room. It is different for every room and changes every time you login.

Method: GET

URI: https://chat.stackoverflow.com/rooms/ROOM_ID

Response

The response will be the HTML of the chat room page. The fkey is located in a hidden form field. It is a 32 character, hexadecimal value (it only contains numbers and the letters a through f).

<input id="fkey" name="fkey" type="hidden" value="FKEY" />

Notes:

  • You can tell if the user has permission to post messages in the room by looking for the <textarea> tag that is used by the end-user for typing in their messages. If the tag is not present, it means the user cannot post messages to the room: <textarea id="input"></textarea>

Getting a URI for connecting to the web socket

Method: POST

URI: https://chat.stackoverflow.com/ws-auth

Parameters:

Name Value
roomid The room ID.
fkey The fkey of the room.

Response example:

{"url" : "wss://chat.sockets.stackexchange.com/events/1/37526a6eb34a4229bf48a3a188b3d247"}

Notes:

  • You must added a parameter named l to the end of the URI in order for the web socket connection to work. The value of this parameter is the timestamp of the room's latest message (see "Get latest messages" method below). For example: wss://chat.sockets.stackexchange.com/events/1/37526a6eb34a4229bf48a3a188b3d247?l=1417005460

Get latest messages

Method: POST

URI: https://chat.stackoverflow.com/chats/ROOM_ID/events

Parameters:

Name Value
mode Always set to "messages" (without quotes)
msgCount The number of messages to retrieve.
fkey The fkey

Response example

{
  "events" : [
    {
      "event_type" : 1,
      "time_stamp" : 1501615302,
      "content" : "<b>hello</b> world",
      "user_id" : 1064310,
      "user_name" : "Tristan Wiley",
      "room_id" : 1,
      "message_id" : 38442657,
      "message_stars" : 1
    },
    {
      "event_type" : 1,
      "time_stamp" : 1501636568,
      "content" : "two",
      "user_id" : 13379,
      "user_name" : "Michael",
      "room_id" : 1,
      "message_id" : 38446507,
      "message_edits" : 1
    },  
    {
      "event_type" : 1,
      "time_stamp" : 1501636756,
      "content" : "three",
      "user_id" : 13379,
      "user_name" : "Michael",
      "room_id" : 1,
      "message_id" : 38446514
    }
  ],
  "time" : 77918739,
  "sync" : 1501636602,
  "ms" : 0
}

Notes

  • Events are sorted by timestamp.
  • The "message_edits" field is only present if the message has been edited.
  • The "message_stars" field is only present if the message has been starred.

Post message

Method: POST

URI: https://chat.stackoverflow.com/chats/ROOM_ID/messages/new

Parameters:

Name Value
text The message to post
fkey The fkey

Response example

{
  "id" : 38469011,
  "time" : 1501724999
}

Notes

  • Chat messages are formatted in Markdown.
  • Stack Overflow Chat will only recognize the Markdown formatting on messages that are not fixed-width and that do not exceed a single line of text (fixed-width messages are formatted in a monospace font; each line in a fixed-width message begins with four spaces)
  • Single-lined messages cannot be longer than 500 characters.

Edit message

Method: POST

URI: https://chat.stackoverflow.com/chats/messages/MESSAGE_ID

Parameters:

Name Value
text The updated message content
fkey The fkey

Responses

All responses are plain-text. The responses are actually enclosed in double quotes when received off the wire.

  • "ok"
  • "This message has already been deleted and cannot be edited"
  • "It is too late to edit this message."
  • "You can only edit your own messages"
  • An HTTP 302 response means the specified message ID is too large and hasn't ever been assigned to a message.

Notes

  • Messages older than 2 minutes cannot be edited.

Delete message

Method: POST

URI: https://chat.stackoverflow.com/chats/messages/MESSAGE_ID/delete

Parameters:

Name Value
fkey The fkey

Responses

All responses are plain-text. The responses are actually enclosed in double quotes when received off the wire.

  • "ok"
  • "This message has already been deleted."
  • "It is too late to delete this message"
  • "You can only delete your own messages"
  • An HTTP 302 response means the specified message ID is too large and hasn't ever been assigned to a message.

Notes

  • Messages older than 2 minutes cannot be deleted.

Get user info

Method: POST

URI: https://chat.stackoverflow.com/user/info

Parameters:

Name Value
ids A comma-separated list of user IDs.
roomId The room ID that the users are in. This is needed because this method tells you if the user is a room owner.

* fkey parameter is not needed

Response example:

{
  "users" : [
    {
      "id" : 13379,
      "name" : "Michael",
      "email_hash" : "!https://i.stack.imgur.com/awces.jpg?s=128\u0026g=1",
      "reputation" : 23145,
      "is_moderator" : false,
      "is_owner" : true,
      "last_post" : 1501724997,
      "last_seen" : 1501770855
    },
    {
      "id" : 2764866,
      "name" : "Wietlol",
      "email_hash" : "f5166c4602a6deaf2accdc98c89e9b82",
      "reputation" : 408,
      "is_moderator" : false,
      "is_owner" : null,
      "last_post" : 1501769545,
      "last_seen" : 1501771253
    }
  ]
}

Notes:

  • If the email_hash field is a hexadecimal string, it means the user uses the default gravatar image for their profile picture (they have not assigned a profile picture to their account). The gravatar image can be retrieved through this URL: https://www.gravatar.com/avatar/HEX?d=identicon&s=128

Get "pingable" users

Gets a list of users that will receive a notification alert if they are mentioned (presumably).

Method: GET

URI: https://chat.stackoverflow.com/rooms/pingable/ROOM_ID

Response:

The response is an array of arrays. Each sub-array contains the following information:

[USER_ID, "USER_NAME", LAST_TIME_BROWSER_PINGED_THE_ROOM?, LAST_POST]

Response example:

[
  [871050, "Madara Uchiha", 1501806907, 1501762902],
  [7035175, "Jenna Sloan", 1501806908, 1501786447],
  [3441199, "Sayros", 1501806908, 1501769411],
  [13379, "Michael", 1501806926, 1501769526],
  [6707985, "geisterfurz007", 1501806926, 1501776474],
  [3763850, "Gemtastic", 1501806926, 1500559606],
  [4258326, "OakBot", 1501806934, 1501802068]
]

Get room info

Method: GET

URI: https://chat.stackoverflow.com/rooms/thumbs/ROOM_ID

Response example:

{
  "id" : 1,
  "name" : "Sandbox",
  "description" : "Where you can play with regular chat features (except flagging) without upsetting anyone",
  "isFavorite" : true,
  "usage" : null,
  "tags" : "\u003ca rel=\"noopener noreferrer\" class=\"tag\" href=\"http://stackoverflow.com/tags/sandbox/info\"\u003esandbox\u003c/a\u003e \u003ca rel=\"noopener noreferrer\" class=\"tag\" href=\"http://stackoverflow.com/tags/sandbox/info\"\u003esandbox\u003c/a\u003e"
}

Leave room

Method: POST

URI: https://chat.stackoverflow.com/chats/leave/ROOM_ID

Parameters:

Name Value
quiet Must be set to "true", otherwise it won't work.
fkey The fkey

Leave all rooms

Method: POST

URI: https://chat.stackoverflow.com/chats/leave/all

Parameters:

Name Value
quiet Must be set to "true", otherwise it won't work.
fkey The fkey of any room you are currently connected to.
Add a custom footer
Add a custom sidebar
Clone this wiki locally