Socket basics

The Talo Socket provides an easy way for you to add interactivity to your game. Using sockets you can send messages between players and allow your game client to be reactive to changes (e.g. new channel messages).

Message structure

The socket used by Talo follows the web socket standard and is compatible with libraries that also do the same.

One major difference is that the Talo Socket will validate messages against a request type and payload structure. For example, if you send a message with the v1.players.identified request, your payload's data must also match the expected schema. The list of available requests and responses are available on their respective pages.

Using the identification example, here is the JSON expected by the Talo Socket when identifying a player:

{
  "req": "v1.players.identified",
  "data": {
    "playerAliasId": 105,
    "socketToken": "9aae3c26-98d0-4a13-9dd7-b187aa36f6cd"
  }
}

The request type is defined by the req key and the payload of the request is defined using the data key.

Responses use a similar message structure, except that req is replaced by res to denote a response:

{
  "res": "v1.players.identified.succes",
  "data": {
    "id": 105,
    "service": "username",
    "identifier": "billy",
    "player": {
      "id": "85d67584-1346-4fad-a17f-fd7bd6c85364",
      "props": [],
      "devBuild": false,
      "createdAt": "2024-10-25T18:18:28.000Z",
      "lastSeenAt": "2024-12-04T07:15:13.000Z",
      "groups": []
    },
    "lastSeenAt": "2024-12-04T07:15:13.000Z",
    "createdAt": "2024-10-25T18:18:28.000Z",
    "updatedAt": "2024-12-04T07:15:13.000Z"
  }
}

Authentication

The Talo Socket provides two layers of authentication:

1. You must provide your access key. This identifies your game and the key's scopes are used to determine whether a client should be sent a message.
2. When players are identified, a socketToken is stored against the player alias for 1 hour. While the socket token is valid, you can use it to authenticate your player with the socket.

info

Not all requests and responses will need a player to be identified. However, your access key will need the read:players scope to identify players.

warning

Unlike the HTTP API, players cannot be created during identification. To successfully identify a player, their alias must already exist in Talo.

Error responses

Due to the nature of sockets, error responses are completely asynchronous. Error responses follow a standard format so you can match them up against your requests. For example:

{
  "res": "v1.error",
  "data": {
    "req": "v1.players.identify",
    "message": "Invalid socket token",
    "errorCode": "INVALID_SOCKET_TOKEN"
  }
}

Some errors may also return a "cause" key which drills down into why a request failed:

{
  "res": "v1.error",
  "data": {
    "req": "v1.channels.message",
    "message": "An error occurred while processing the message",
    "errorCode": "LISTENER_ERROR",
    "cause": "Player not in channel"
  }
}

For a more detailed look into the available error codes, visit the common errors page.