Realtime | Morpheus Platform Docs

Connect to the realtime service

get

Creates a websocket connection to the realtime service, sending messages to the realtime service will subscribe you to different resources allowing you to listen to document updates in realtime. When subscribing if a resource doesn't exist yet a listener will be created and will be triggered when the resource is created. If the resource is deleted the listener will still exist so make sure to unsubscribe when you no longer need the resource.

When connecting via a html websocket you will need to parse all of your headers in through Sec-WebSocket-Protocol which is an optional header that takes in a string. Format for the string needs to be a list of headers split by \n and key value split by : and then encoded into base58

Example format

x-m2-organization:testOrg x-m2-project:testProj

Example messages for subscribing to the resources available in the realtime service -

KVStore:

  {
      "action": "subscribe",
      "resource": {
          "type": "kvStore",
          "id": "World:kvstoreClient:testKey"
      }
  }

Collections:

  {
      "action": "subscribe",
      "resource": {
          "type": "collection",
          "id": "public"
      }
  }

Liveconfig:

  {
      "action": "subscribe",
      "resource": {
          "type": “liveConfig",
          "id": “game"
      }
  }

Using the same format, you can also unsubscribe from the resources by changing the action to "unsubscribe" and sending the same resource.

Example response formats below.

Success:

    {
      "userId": "fakeUserId",
      "resource": {
          "type": "collection",
          "id": "private"
      },
      "data": {
          "userId": "fakeUserId",
          "datasourceId": "fakeDatasourceId",
          "userCollection": []
      },
      "version": "2024-01-30T15:50:35.742Z"
    }

Warning:

    {
      "warning": "resource_not_found",
      "message": "KVStore resource doesn't currently exist, subscription was still made successfully"
    }

Error:

    {
      "error": "Invalid message format"
    }

Authorizations

Header parameters

x-m2-organization-idstringRequired

The ID of an organization

x-m2-project-idstringOptional

The ID of a project

x-m2-world-idstringOptional

The ID of a world

Responses

101

Default Response

application/json

Responseany of

stringOptional

Provides information about the service status.

4XX

The error object returned by the API when an error occurs

application/json

get

GET /api/realtime/connect/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
Accept: */*

text