Docs

Thanks for checking out Gossip.

Before continuing, you should create an account or sign in.

Game Configuration

Once you have an account, visit your configuration page. This will let you create a game on Gossip. It will then show you your Client ID and Client Secret which will be used to authenticate against the Gossip network.

Channels

You also subscribe to the channels you want your game to pay attention to. Right now Gossip has the following channels:

  • gossip
  • testing
  • announcements

In addition to those listed above, you can subscribe to any valid channel name. This will dynamically create channels as you subscribe to them. They will exist for anyone to connect to, but not show on the website until the admins approve them.

A valid channel name must be between 3 and 15 characters (inclusive), letters (a-zA-Z), _, and - only.

You will only recieve messages for channels you are subscribed to.

Server Support

The following servers/frameworks have built-in support or a library to import for Gossip support:

Connecting

Once you have your Client ID and Client Secret, you can start connecting to the Gossip network. Point your websocket client at:

wss://gossip.haus/socket

Once you are connected, you must send an authenticate message to authenticate your connection.

Expectations of a Connecting Game

If you are connecting to the Gossip network, please know that you connect under the following assumptions:

  1. Gossip will go down sometime while you are connected. Most likely for a new deploy. Make sure your game does not crash because of this.
  2. While Gossip is down, your app should transition channels to local only.
  3. Similarly, you should reconnect back to Gossip when it comes back online.
  4. You must support UTF-8 at the server level. Several connected games allow UTF-8 input so you may receive it at any time.

It is suggested to follow these:

  1. Formatting for player names should be in the format of Player@GameName.

Common Vocabulary

  • ref is a unique reference that identifies an event in a request and response. This should be a UUID.
  • channel is the name of a channel on Gossip.
  • game is the short name of a connected game.
  • name is the name of a player in a connected game.

Socket Error Codes

4000
Authentication failed
4001
Heartbeat failure

Core Events (channels)

Since 1.0.0

These are the core features of connecting to Gossip. These include authenticating, a heartbeat, basic public channels.

authenticate

Since 1.0.0

This event authorizes the connection and afterwards you will start to receive new broadcasts.

{
  "event": "authenticate",
  "payload": {
    "client_id": "client id",
    "client_secret": "client secret",
    "supports": ["channels"],
    "channels": ["gossip"],
    "version": "1.0.0",
    "user_agent": "ExVenture 0.23.0"
  }
}
  • supports is required. This is an array of features the connecting game supports. It must contain at least channels. Extra unknown options will result in the socket being disconnected.
  • channels is optional. This is an array of channels you wish to subscribe to on start. See the list of channels for available channels you can subscribe to.
  • user_agent is optional but suggested. If present, this will show on the Games page.
  • version is optional but suggested. This is highest version number that you as a client know of. As Gossip updates, it will be able to alert you that there are new features available. If not present, then a default of 1.0.0 is used.

You will receive a response from this with a sucess or failure message.

{
  "event": "authenticate",
  "status": "success"
  "payload": {
    "unicode": "✔️",
    "version": "2.2.0"
  }
}
  • unicode is present to ensure you properly parse unicode characters.
  • version is the current version of Gossip.

If you attempt to subscribe to bad channels, you may receive a failed subscribe message. See more above about valid channel names.


heartbeat

Since 1.0.0

Once you are authenticated, the server will start sending heartbeat events.

{
  "event": "heartbeat",
}

When you receive a heartbeat, you must respond to it with a heartbeat of your own.

{
  "event": "heartbeat",
  "payload": {
    "players": ["player"]
  }
}
  • players is optional but suggested. You should include your full player list to keep Gossip in sync with you. Gossip must know your players are online to forward remote tells.

NOTE: If you do not respond to these heartbeats the socket will be closed after three failed beats.


restart

When Gossip knows a restart is imminent, you will receive this event. This event will be sent before a server restart due to a deploy.

After receiving this event, your connection to Gossip may drop at any moment.

{
  "event": "restart",
  "ref": "f15ed228-ad43-4af4-9466-7d353fc9bf11",
  "payload": {
    "downtime": 15
  }
}
  • downtime is a suggested amount of seconds you should wait before restarting. It is a hint from the server for how long it thinks Gossip will be down.

channels/subscribe

Since 1.0.0

Subscribe to a new channel on your currently connected socket.

{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b",
  "payload": {
    "channel": "gossip"
  }
}
  • ref is optional.
  • channel is required.

If a ref is included then you will get a response back confirming your message.

{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b"
}

You may receive a response to this as a failure, channel names are validated. See more above about valid channel names.

{
  "event": "channels/subscribe",
  "ref": "a6f8006d-ddac-465e-a3df-fb440e83189b",
  "status": "failure",
  "error": "Could not subscribe to 'bad channel name'",
}

channels/unsubscribe

Since 1.0.0

Unsubscribe to a channel you are subscribed to.

{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466",
  "payload": {
    "channel": "gossip"
  }
}
  • ref is optional.
  • channel is required.

If a ref is included then you will get a response back confirming your message.

{
  "event": "channels/unsubscribe",
  "ref": "e4d07334-4a4b-44ba-94dc-2b937160a466"
}

channels/broadcast

Since 1.0.0

When a channel you are subscribed to receives a new message you will get a broadcast.

{
  "event": "channels/broadcast",
  "ref": "89036074-446f-41ab-b87a-44ef1f962f2e",
  "payload": {
    "channel": "gossip",
    "message": "Hello everyone!",
    "game": "ExVenture",
    "name": "Player"
  }
}

channels/send

Since 1.0.0

To send a new message, use this event.

The message in the payload will have MXP tags stripped before broadcasting. Do not send MXP data.

You will not get a channels/broadcast event for messages you send.

{
  "event": "channels/send",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b",
  "payload": {
    "channel": "gossip",
    "name": "Player",
    "message": "Hello everyone!"
  }
}
  • ref is olitional.
  • channel is required. channel must be a channel you are subscribed to.
  • name is required.
  • message is required.
  • See Common Vocabulary for payload data.

If a ref is included then you will get a response back confirming your message.

{
  "event": "channels/send",
  "ref": "28523394-6dcf-4c2a-ad1d-2d0ef8bb823b",
}

Player Events (players)

Since 1.0.0

These events are related to the players support flag. Add this to your supports array when connecting.

players/sign-in

Since 1.0.0

When a player signs into your game, send this message. It will broadcast to other games and also update Gossip's tracking of who is signed in.

You will not receive a players/sign-in event back for messages you send.

{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f",
  "payload": {
    "name": "Player"
  }
}

If a ref is included then you will get a response back confirming your message.

{
  "event": "players/sign-in",
  "ref": "0e11c053-65b3-477c-aae9-5cd8cf21dc8f"
}

While connected with the players flag, you may receive an update from another game. You may wish to broadcast to your local players that someone has come online in the network.

{
  "event": "players/sign-in",
  "payload": {
    "game": "ExVenture",
    "name": "Player"
  }
}

See Common Vocabulary for information on payload data.

Note: you must still respond to heartbeats with your full list. Each beat fully replaces the list ensuring it keeps in sync. This is for between the beats and notifying connected games.


players/sign-out

Since 1.0.0

When a player signs out of your game, send this message. It will broadcast to other games and also update Gossip's tracking of who is signed in.

You will not receive a players/sign-out event back for messages you send.

{
  "event": "players/sign-out",
  "ref": "da4c5503-dd15-490a-9d0d-85e2c50b72de",
  "payload": {
    "name": "Player"
  }
}

If a ref is included then you will get a response back confirming your message.

{
  "event": "players/sign-out",
  "ref": "da4c5503-dd15-490a-9d0d-85e2c50b72de"
}

While connected with the players flag, you may receive an update from another game. You may wish to broadcast to your local players that someone has gone offline in the network.

{
  "event": "players/sign-out",
  "payload": {
    "game": "ExVenture",
    "name": "Player"
  }
}

See Common Vocabulary for information on payload data.

Note: you must still respond to heartbeats with your full list. Each beat fully replaces the list ensuring it keeps in sync. This is for between the beats and notifying connected games.


players/status

Since 1.1.0

To check the status of other players on the network, send a players/status event.

{
  "event": "players/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4"
}

ref is required.

In response you will receive a message per connected game.

{
  "event": "players/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
     "game": "ExVenture",
     "players: ["admin"]
  }
}
  • players is the list of players that are currently online.
  • See Common Vocabulary for payload data.
Single Game Update

You can request an update to a single game by adding its name in the payload.

{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
    "game": "ExVenture"
  }
}

You will only receive an update for that game. It will look the same as above.


Tell Events (tells)

Since 2.0.0

These events are related to the tells support flag. Add this to your supports array when connecting.

It is suggested to also support the players flag, as you can keep your players' status more up to date on Gossip. Players must be online on Gossip to receive tells.

tells/send

Since 2.0.0

{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "payload": {
    "from_name": "Player",
    "to_game": "ExVenture",
    "to_name": "eric",
    "sent_at": "2018-07-17T13:12:28Z",
    "message": "hi"
  }
}
  • ref is required.
  • from_name is required. This is the name of the player sending the tell.
  • to_game is required. This is the name of the game that will process the tell. The server will match this case insensitive against connected games.
  • to_name is required. This is the name of the receiving player.
  • sent_at is required. This is an ISO8601 formatted timestamp of when the message was sent. It must be in UTC, use the Z format for UTC.
  • message is required. This is the body of the tell.

If the game and player are online, you will receive a response back.

{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "status": "success"
}

If the tell did not succeed in sending, you will receive an error response.

{
  "event": "tells/send",
  "ref": "5c528fc3-cb9e-4867-98ea-6e235594241e",
  "status": "failure",
  "error": "game offline"
}

Possible failure responses are:

  • game offline
  • sending player offline
  • receiving player offline
  • not supported, the connected game does not support tells

tells/receive

Since 2.0.0

When another game sends a tell to your game, you will receive this event.

{
  "event": "tells/receive",
  "ref": "d4a08749-acbe-45ab-bc0f-51609fd6b95b",
  "payload": {
    "from_game": "AMud",
    "from_name": "Player",
    "to_name": "eric",
    "sent_at": "2018-07-17T13:12:28Z",
    "message": "hi"
  }
}
  • from_name is the name of the player sending the tell.
  • from_game is the name of the game sending the tell.
  • to_name is the name of the receiving player.
  • sent_at is an ISO8601 formatted timestamp of when the message was sent. It is in UTC.
  • message is the body of the tell.

Game Events (games)

Since 2.1.0

These events are related to the games support flag. Add this to your supports array when connecting.


games/connect

Since 2.2.0

While connected with the games flag, you may receive a connection notice for another game. You may wish to broadcast to your local players that game has come online from the network.

{
  "event": "games/connect",
  "payload": {
    "game": "ExVenture",
  }
}

See Common Vocabulary for information on payload data.


games/disconnect

Since 2.2.0

While connected with the games flag, you may receive a disconnection notice for another game. You may wish to broadcast to your local players that game has gone offline from the network.

{
  "event": "games/disconnect",
  "payload": {
    "game": "ExVenture",
  }
}

See Common Vocabulary for information on payload data.


games/status

Since 2.1.0

To check the status of other games on the network, send a games/status event.

{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4"
}

ref is required.

In response you will receive a message per connected game.

{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "status": "success",
  "payload": {
    "game": "ExVenture",
    "display_name": "An ExVenture game",
    "description": "...",
    "homepage_url": "https://...",
    "user_agent": "ExVenture 0.26.0",
    "user_agent_repo_url": "https://...",
    "connections": [
      {"type": "telnet", "host": "example.com", "port": 4000},
      {"type": "web", "url": "https://example.com/play"}
    ],
    "supports": ["channels", "players", "tells", "games"],
    "players_online_count": 3
  }
}
  • display_name is a less restrictive name for the game.
  • description is text about the game.
  • homepage_url is the home page for the game.
  • user_agent is the reported user agent of the connectin game. May not be present.
  • user_agent_repo_url is a source code repository for the user agent. May not be present.
  • connections is an array of connection objects. See below for more about connections. May not be present
  • supports if the game is currently connected, this is an array of what the socket supports. May not be present.
  • players_online_count if the game is currently connected, the number of players that are online. May not be present.
  • See Common Vocabulary for payload data.
Connection Object

A connection object contains ways of connecting to play the game.

Current connection types are: web, telnet, and secure telnet.

web
This is a web based game.
{
  "type": "web",
  "url": "https://example.com/play"
}
  • type is set to "web"
  • url is a web page to start playing the game.
telnet
This is a standard telnet connection.
{
  "type": "telnet",
  "host": "example.com"
  "port": 4000
}
  • type is set to "telnet"
  • host is the host name to connect to.
  • port is the port to connect to.
secure telnet
This is a TLS secured telnet connection.
{
  "type": "secure telnet",
  "host": "example.com"
  "port": 4000
}
  • type is set to "telnet"
  • host is the host name to connect to.
  • port is the port to connect to.
Query for a Single Game

You can request an update to a single game by adding its name in the payload.

You can also query for games not connected via this event.

{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "payload": {
    "game": "ExVenture"
  }
}

When requesting a single game, you might receive an error response. If the game is unknown.

{
  "event": "games/status",
  "ref": "c8cbaef2-b6e9-4110-b712-a312aee9e7d4",
  "status": "failure",
  "error": "unknown game"
}

You will only receive an update for that game. It will look the same as above.

Grapevine Login

Grapevine is the player half of Gossip. You can integrate a common login through Grapevine by using OAuth 2.0.

For more information on the OAuth 2.0 flow, please check out the spec at OAuth.net.

Grapevine only supports the Authorization Code Grant type.

Redirect URIs

Before starting your integration, make sure to setup your redirect URIs on Gossip. For each game you are integrating, set all of the allowed redirect URIs from the "View" link on the Your Games page.

The redirect_uri must be a secure https URI or a localhost URI for development purposes.

Scopes

When authorizing against Grapevine, you must provide a set of scopes you wish to request from the user. Listed below are the available scopes.

  • profile gets basic profile information about the user, such as a UID and username
  • email can be added with profile to get the user's email address included in the user information response

Authorization

Authorize Route: https://grapevine.haus/oauth/authorize

When authorizing you must provide your client_id, any scope you want, a state to keep track of the request, your redirect_uri, and the response_type must be code

A sample request is listed below.

https://grapevine.haus/oauth/authorize?client_id=YOUR-CLIENT-ID
&scope=profile
&state=STATE
&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fgrapevine%2Fcallback
&response_type=code

Token Generation

Token Route: https://grapevine.haus/oauth/token

To generate an access token from the authorization code from above, POST to the /oauth/token endpoint.

Access tokens expire after 1 hour.

A sample request is listed below.

POST https://grapevine.haus/oauth/token?client_id=YOUR-CLIENT-ID
&code=CODE
&grant_type=authorization_code
&redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fgrapevine%2Fcallback

Fetching User Information

User Information Route: https://grapevine.haus/users/me

Once you have an access token for a user, you can fetch information about the user by doing a request to /users/me

The access token should be provided in the Authorization header as a Bearer token.

A sample request is below.

GET https://grapevine.haus/users/me
Authorization: Bearer my-token
Accept: application/json

200 OK
{
  "uid": "their UID",
  "username": "their username",
  "email": "their email"
}