Integrations overview: push events to external services

Learn how Voxel Telephone’s integration system works, what event types are available, and how to configure multiple integrations in config.json.

Voxel Telephone can push game events to external services — Discord channels, Slack workspaces, in-game announcements, or your server console — using a modular integration system. Each integration subscribes to specific event types called interests, and receives only the messages relevant to it.

How integrations work

When something notable happens on the server — a player connects, a game turn completes, a chat message is sent — the Universe class calls pushMessage with the event and its interest type. Every loaded integration that subscribed to that interest type receives the message and forwards it through its own delivery mechanism.

Integrations are loaded at startup from the integrations array in config.json. Each entry specifies:

• class — the integration to use, matching a file in class/integrations/
• interests — an array of event types the integration should receive
• authData — credentials or configuration specific to the integration (not required for all integrations)
• language — optional locale code for formatted messages (defaults to "en")

{
  "integrations": [
    {
      "class": "DiscordWebhook",
      "authData": {
        "webhookUrl": "https://discord.com/api/webhooks/..."
      },
      "interests": [
        "gameProgression",
        "playerConnection",
        "announcement"
      ]
    },
    {
      "class": "ConsoleLog",
      "interests": [
        "startServer",
        "chatMessage"
      ]
    }
  ]
}

Interest types

Each integration subscribes to one or more of the following interest types. Use only the string values listed here in your interests array.

Interest type	Description
gameProgression	A game turn was completed or another game-related milestone occurred.
chatMessage	A player sent a chat message in the game.
playerConnection	A player connected to or disconnected from the server.
announcement	A periodic tip or announcement was triggered by the announcement scheduler.
startServer	The server finished starting up.

Built-in integrations

Four integrations ship with Voxel Telephone. The class field in your config must match the class name exactly.

Class	Description
DiscordWebhook	Posts messages to a Discord channel via an incoming webhook URL.
Slack	Posts messages to a Slack channel using a bot token.
ServerAnnouncement	Broadcasts messages to all connected players in-game.
ConsoleLog	Prints messages to the server’s standard output.

ServerAnnouncement and ConsoleLog do not require an authData field.

Configuring multiple integrations

You can add as many entries to the integrations array as you need. Each runs independently, and an event is delivered to every integration that lists the matching interest type.

The example below sends game progression events to Discord, routes chat messages to Slack, and broadcasts announcements to all players in-game:

{
  "integrations": [
    {
      "class": "DiscordWebhook",
      "authData": {
        "webhookUrl": "https://discord.com/api/webhooks/..."
      },
      "interests": ["gameProgression", "playerConnection"]
    },
    {
      "class": "Slack",
      "authData": {
        "token": "xoxb-your-bot-token",
        "channel": "#voxel-telephone"
      },
      "interests": ["chatMessage"]
    },
    {
      "class": "ServerAnnouncement",
      "interests": ["announcement"]
    }
  ]
}

If you omit the integrations key entirely from config.json, the server starts with no integrations loaded.

Integration pages

Discord webhook

Post game events to a Discord channel using an incoming webhook URL.

Slack

Forward server events to a Slack channel using a Slack bot token.