Use the broadcast service to create a message thread and publish messages to subscribers.

• A broadcast call can target a single viewer, a subset of viewers on a channel, or all viewers on a channel.
• An extension-broadcast call targets all viewers that are currently using the extension.
• A whisper-self call enables back-channel communication for coordinating and synchronizing multiple instances of an extension.

The publisher names an event stream, which identifies a message thread. Extensions use the GameLink library and WebSocket protocol to subscribe to the named event and register a callback handler for notifications. See Event Handling for more information.

Message format

The body of an broadcasting request contains the message data as an arbitrary developer-defined JSON object.

🚧

Message size limit

A message object that is larger than 4kb is automatically compressed, then base64-encoded. If the resulting base64-encoded string is still longer than 4kb, the broadcast call fails. If the call succeeds, the service decodes and decompresses the data transparently.

This means that the effective maximum size of the JSON object sent by broadcast is not well defined, but 6kb is a safe size.

Authorization

Thread creation and message publishing calls can be made by authenticated users with the broadcaster or admin role.

The broadcast endpoint can also be used for server-to-server communication.
Authorization for a call from a backend server to the Muxy server requires a self-signed token with the field "role": "backend". This can be established with a JWT claim by someone who knows the JWT signing secret, generally assumed to be the extension developer.

📘

Broadcasting during development

Broadcasts sent in the sandbox environment do not trigger events in the production environment, or vice versa.

Sending a Channel Broadcast

An authorized user with a backend or admin role can use a GET request to the broadcast endpoint to send a message to any channel, or to a specific viewer on the channel.

Request

GET /v1/e/broadcast

The body of the request contains the following JSON-encoded data.

{
    "target": string,
    "event": string,
    "user_id": string,
    "data": object
}

Response

If the call succeeds, the body of the response contains an empty JSON object. If it fails, the body of the response contains error information.

Sending an Extension-wide Broadcast

The owner or administrator of an extension (an authorized user with a backend or admin role) can use a GET request to the extension_broadcast endpoint to send a message to all viewers on all channels with the extension loaded, or to a specific viewer on any channel.

Request

GET /v1/e/extension_broadcast

The body of the request contains the following JSON-encoded data.

{
    "target": string,
    "event": string,
    "data": object
}

Response

If the call succeeds, the body of the response contains an empty JSON object. If it fails, the body of the response contains error information.

Sending a Back-channel Message

Use the whisper_self endpoint to synchronize multiple instances of an extension.
Notifications can be processed on a broadcaster configuration page while the broadcaster is interacting with the viewer extension.

Request

A GET request broadcasts a message to all viewing clients that the caller is currently watching, in the same channel that the request was made from.

GET /v1/e/whisper_self

The body of the request contains the following JSON-encoded data.

{
    "event": string,
    "data": object
}

Response

If the call succeeds, the body of the response contains an empty JSON object. If it fails, the body of the response contains error information.