Skip to main content
Agents can send messages to you via the SDK. Messages appear in the Messages panel in orch-hq and are accessible via the API. Use them for daily briefings, error alerts, completion notifications — anything your agent wants to tell you.

​
Quick Start

from orchagent import message

message.send("Daily Brief", "Here's what happened today...")
That’s it. The message appears in your orch-hq Messages panel immediately.

​
Messages vs Run Output

Every agent run produces output_data — visible in the Activity Feed. But not every run output is worth surfacing as a notification. A Discord bot responding to a user produces output, but showing one side of that conversation as a message is noise. Messages are intentional. You decide what’s worth surfacing by calling message.send() explicitly. This separates “agent did work” (Activity Feed) from “agent has something to tell you” (Messages).

​
SDK Usage

from orchagent import message

# Simple message
message.send("Daily Brief", "Here's what's happening today...")

# With level (affects display in orch-hq)
message.send("Build Failed", "Error in main.py line 42", level="error")

# With metadata
message.send(
    "Report Ready",
    "Monthly revenue report generated.",
    level="success",
    metadata={"report_url": "https://..."}
)

​
Parameters

ParameterTypeRequiredDescription
titlestrYesShort subject line
bodystrYesFull message content (plain text or markdown)
levelstrNoinfo, success, warning, or error (default: info)
agent_namestrNoOverride sender name (auto-detected normally)
metadatadictNoArbitrary extra data (stored as JSON)

​
Levels

LevelUse forDisplay
infoBriefings, status updatesBlue dot
successCompleted tasks, reports readyGreen dot
warningDegraded performance, approaching limitsOrange dot
errorFailures, broken thingsRed dot

​
API Reference

All endpoints require Authorization: Bearer <api_key>.

​
Send a message

curl -X POST https://api.orchagent.io/messages \
  -H "Authorization: Bearer $ORCHAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daily Brief",
    "body": "Here'\''s what'\''s happening...",
    "level": "info",
    "metadata": {"source": "morning-brief"}
  }'
Response (201): 
{
    "id": "uuid",
    "agent_name": "morning-brief",
    "title": "Daily Brief",
    "level": "info",
    "created_at": "2026-03-14T08:00:00Z"
}

​
List messages

GET /messages?limit=50&offset=0&level=error&agent_name=morning-brief
ParameterTypeDefaultDescription
limitint50Max messages to return
offsetint0Pagination offset
levelstr—Filter by level
agent_namestr—Filter by agent name
Response: 
{
    "messages": [...],
    "total": 42
}

​
Workspace-scoped listing

GET /workspaces/{workspace_id}/messages?limit=50
Same query parameters as GET /messages, scoped to a specific workspace.

​
Delete a message

DELETE /messages/{message_id}

​
orch-hq Display

Messages appear in the Messages panel (sidebar button) in orch-hq:
  • Level dot (colored by severity)
  • Agent name, title, and body preview
  • Relative timestamp (“2m ago”, “1h ago”)
  • Click to expand full body
  • Polls every 15 seconds for new messages

​
Examples

​
Morning briefing agent

from orchagent import message

# Compile your brief from whatever sources
brief = compile_morning_brief()

# Send to orch-hq (in addition to any other channels)
message.send("Morning Brief", brief)

​
Error monitor

from orchagent import message

errors = check_for_errors()
if errors:
    message.send(
        f"{len(errors)} Errors Detected",
        "\n".join(f"- {e}" for e in errors),
        level="error"
    )

​
Deployment notification

from orchagent import message

message.send(
    "Deployed v2.3.1",
    "Backend deployed to production. All health checks passing.",
    level="success",
    metadata={"version": "2.3.1", "environment": "production"}
)
Messages are additive. If your agent already sends to Telegram or Discord, add message.send() alongside your existing delivery code — one extra line puts the message in orch-hq too.

​
Next Steps

Tasks

Create and manage tasks from your agents

SDK Reference

Full SDK documentation

orch-hq

The desktop app where messages appear