Skip to content
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

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

Access and settings

  • Over HTTP, a system API answers once its settings give it apiAccessType: TOKEN_ACCESS (the token of an API user whose group grants this system API, in x-am-authorization) or IS_PUBLIC. Without settings it is NO_ACCESS : your code calls it through g.sys, the admin panel tests it, and an HTTP call is refused. The group must also grant the WebSocket event.
  • The settings can also cache the answer or require person tokens (authProviders) ; pre and post hooks run around it like around any API.
  • The request headers apply : x-am-response-case, x-am-content-type-response, x-am-internationalization, x-am-tenant-username…

Errors

Code When
400 The body is wrong : the message names the missing or invalid key, WebSocket event not found with name … for an unknown event.
401 No valid API user token, or the API is NO_ACCESS : You are not authorized to access this API.
403 No group grants this system API.