This page View Markdown Open in ChatGPT Open in Claude

Emit WebSocket event¶

Sends the data to every client subscribed to a custom WebSocket event whose subscription condition matches, whatever server the client is connected to.


Method	POST
URL	`/api/system-api/admin/emit-event-ws` : `admin` is the user path of your account
Body	`{ name, eventData? }` or an array of them
Answer	`data` : `true`
From code	`g.sys.system.emitEventWS`

The call¶

Body

{ "name": "default/orders-updated", "eventData": { "recipientId": "42", "order_no": 1001, "status": "SHIPPED" } }

Body : several events

[
    { "name": "default/orders-updated", "eventData": { "recipientId": "42", "order_no": 1001 } },
    { "name": "stock-alerts", "eventData": { "sku": "WM-1", "qty": 2 } }
]

The event must exist on the WebSocket Events page. A client receives the data when its subscription has no condition, or when the emitted data has the values of its criteria.
To notify one person, put their id in the data and let their client subscribe with that id in criteria.

From code¶

TypeScriptPythonPHPC#GoRustJavaKotlin

await g.sys.system.emitEventWS('default/orders-updated', { recipientId: '42', order_no: 1001 });

await g.sys.system.emit_event_ws('default/orders-updated', {'recipientId': '42', 'order_no': 1001})

$g->sys->system->emitEventWS('default/orders-updated', ['recipientId' => '42', 'order_no' => 1001]);

await g.Sys.System.EmitEventWS("default/orders-updated", new JsonObject { ["recipientId"] = "42", ["order_no"] = 1001 });

if _, err := g.Sys.System.EmitEventWS("default/orders-updated", am.M{"recipientId": "42", "order_no": 1001}); err != nil {
    return nil, err
}

g.sys.system.emit_event_ws("default/orders-updated", json!({ "recipientId": "42", "order_no": 1001 }))?;

g.sys.system.emitEventWS("default/orders-updated", Map.of("recipientId", "42", "order_no", 1001));

g.sys.system.emitEventWS("default/orders-updated", mapOf("recipientId" to "42", "order_no" to 1001))

An unknown event answers 400 : WebSocket event not found with name ….

Access, headers and errors¶

Over HTTP, a system API answers only once its settings open it : TOKEN_ACCESS (the token of an API user whose group grants this system API) or IS_PUBLIC. Without settings it is NO_ACCESS : only your code (g.sys) and the admin panel reach it.
The settings can also keep the answer in the cache, or ask for the token of a person (authProviders). Pre and post hooks run around it, as around any API.
It takes the request headers and answers the envelope. 401 : no valid token, or the API is NO_ACCESS. 403 : no group grants it. 400 : the body is wrong, and the message names the key.