External communication

External communication is a feature that allows you to exchange data between a server outside of cluster and the space instance. It can be used with ItemScript.

The server must generally be managed by the creator themselves or by a trusted third party. You can register one server URL per creator account. All worlds and items created by the creator will communicate with the registered server. When external communication is initiated from a craft item, it accesses the server of the creator of that item.

Player privacy

External communication is a powerful feature that enables sending and receiving data between the space instance and an external server. To protect player privacy, external communication is carried out through cluster’s servers.

To transmit personal information related to a player, player consent is required.

If it is suspected that personal information is being transmitted, we may inquire about its intended use. If we determine that the use is inappropriate, we may restrict usage without prior notice.

Preparing and registering the server

The external communication server must provide an endpoint that accepts HTTP POST requests.

Each time the external communication API is called, an HTTP POST request will be sent to the endpoint. The data included in the response to the POST request will be passed to onExternalCallEnd. If the endpoint does not respond within the 5-second timeout or returns an error, the attempt is considered a failure. Cluster does not retry the request to the endpoint.

Request

{
  "request": "...string less than 1kB..."
}

Response

{
  "verify": "...verify_token...",
  "response": "...string less than 1kB..."
}

Only one server endpoint can be registered per creator. If external communication is used for multiple purposes across different content, you can add a field to the request to distinguish the purpose and route the processing accordingly.

For high-load processes that may exceed 5 seconds, you can split the request from ClusterScript into a start-processing request and a result-checking request, and periodically check for results to ensure completion.

Token issuance and URL registration

You can register or change the URL by selecting “Cluster > External communication (callExternal) destination URL” from Creator Kit. Once the URL is registered, a token will be displayed in the window. This token is used by cluster to confirm that the server is under the control of the creator.

The token is required for communication. Since the token is only displayed once, make sure to copy and save it elsewhere. Additionally, note that the token changes each time a new URL is registered.

Using the callExternal API

To perform external communication, use the following APIs: