API-Machine Messages

note

Preliminary: subject to change

The Machine Messages API sends an operator message to one or more machines — the same message dialog the operator-messages panel raises in the Eclipse Pro UI. A message can carry a color and can optionally halt the line.

This endpoint is fire-and-forget: a 202 Accepted confirms the message was accepted for delivery to the machine, not that it was displayed or acknowledged.

See API-Getting Connected for the Authorization: ApiKey ... header.

Conventions

• License gate. Every target machine must carry the pro.machine.licensed claim. If you list a machine that does not, the whole request is rejected with 403 and nothing is sent — there is no partial delivery.
• Send to all licensed machines. Omit machineNumbers (or send an empty array) to send to every machine that carries pro.machine.licensed.
• Multi-line messages. Put real newline characters (\n) in the message string. A maximum of 9 lines is allowed.
• Colors are string names. color is sent as a name like "Red" — not a number. See Message colors.

Endpoints

POST /api/v1/machines/messages (send an operator message)

Body

{
  "message": "Line one\nLine two",
  "machineNumbers": ["1", "2"],
  "color": "Red",
  "haltLine": false,
  "source": "MES integration"
}

field	required	description
message	yes	The message body. Multi-line via \n; max 9 lines.
machineNumbers	no	Machine numbers to send to, as strings (e.g. ["1", "2"]). Each must be licensed (pro.machine.licensed). Empty or omitted → all licensed machines. A value that is not a machine number returns 400.
color	no	Dialog color, by name (e.g. "Grey", "Red"). Omit for grey. See Message colors.
haltLine	no	When true, the message halts the line (sent as an error dialog). Default false.
source	no	Free-text label recorded with the message in the log. Default "Public API".

Responses

http code	content-type	response
202	—	Accepted for delivery. Fire-and-forget; no body.
400	application/json	Validation failure: empty message, more than 9 lines, an unrecognized machine number, or no machine is licensed. Body: { "errors": [...] }.
403	application/json	One or more listed machines are not licensed. Body lists them: { "errors": ["Not licensed ... for machine(s): 3, 4"] }.
503	application/json	The Classic agent is offline; the message was not delivered. Body: { "errors": ["AgentNotAvailable"] }.
401	application/json	Missing or invalid API key.

Example cURL

Send a halting red message to machines 1 and 2:

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"message":"Stop and check coil\nSee supervisor","machineNumbers":[1,2],"color":"Red","haltLine":true}' \
     "http://localhost:8080/api/v1/machines/messages"

Send an informational message to all licensed machines:

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"message":"Shift change in 10 minutes"}' \
     "http://localhost:8080/api/v1/machines/messages"

Message colors

The color field is one of the following string names. Omit color for grey.

value	appearance
Grey	Grey. Same as omitting color.
Red	Red.
Yellow	Yellow.
Green	Green.
Blue	Blue.

Any other value is rejected with 400. Color controls appearance only — it does not halt the line. To halt the line, set haltLine: true (independent of color).