Send a targeted message

POST /messages sends a message to everyone matching a filter, right now. There's no confirmation step — the request sends as written.

curl -X POST "https://mcp.onkey.chat/functions/v1/rest-api/messages" \
  -H "Authorization: Bearer okm_<your-token-here>" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Please submit your hours by Friday.",
    "filter": { "location": "Glendale" }
  }'

const res = await fetch("https://mcp.onkey.chat/functions/v1/rest-api/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer okm_<your-token-here>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    body: "Please submit your hours by Friday.",
    filter: { location: "Glendale" },
  }),
});
const { sent_to, message_id } = await res.json();
console.log(`Sent to ${sent_to} workers`);

The filter must set at least one of name, location, or role. If it matches nobody, you still get a 200 with "sent_to": 0 — not an error.

Send to everyone

To reach every active worker on your Agent, at every location, send "everyone": true instead of a filter:

{
  "subject": "Uniform policy",
  "body": "The new uniform policy starts Monday.",
  "everyone": true
}

Send one or the other: everyone together with a filter is a 400, and so is a request with neither. An empty filter never means everyone.

🚧
One request reaches your whole team
There's no confirmation step and no rate limit on a message to everyone. Make sure your integration only sets everyone when that is really what was asked for. For urgent news, use an alert (POST /alerts) instead — see below.

📘
Messages vs. alerts
Messages — targeted or to everyone — are not rate-limited. They land in each worker's Inbox and suit routine news. Broadcast alerts (POST /alerts) share a cap across every channel — see Rate limits.

For the full request and response schema, see the API Reference.

Next steps

List your active mobile users — find the right audience for a message.
Errors — the error format and every status code.