SymDocs
Workspace API
All productsSym Workspace APISym Passes MCP
Supportjoinsym.com ↗
Sym Workspace API

Send a message

Queue a user-authored message through the same durable SYM-node and Gateway flow used by SYM-OS. Hermes slash commands are preserved exactly; send /new to request a reset of this exact chat's current Hermes conversation.

API 2.7.0 · Published service contract ↗

Request

Base URL: https://app.sym.so/v1/workspaces/{workspace_id}

Authentication: bearer. Required scope: messages:send.

POST /agents/{agent_id}/chats/{chat_id}/messages

Queue a user-authored message through the same durable SYM-node and Gateway flow used by SYM-OS. Hermes slash commands are preserved exactly; send /new to request a reset of this exact chat's current Hermes conversation.

ParameterTypeDescription
agent_id
path · required
stringRequired agent_id path identifier.
chat_id
path · required
stringAccessible chat ID.
Idempotency-Key
header · required
stringClient-generated key that prevents duplicate work.
response_context
body
objectOptional per-message presentation metadata: {"channel":"voice","verbosity":"concise"}. Requests a brief conversational reply without reducing task completeness or changing profile instructions. Omit for ordinary text turns. Requires a worker supporting this contract; keep the original content unchanged.
Request
curl --fail-with-body -X POST "https://app.sym.so/v1/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $SYM_WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"content\":\"/new\",\"client_message_id\":\"reset-chat-unique-001\"}"
Response 200
{
  "worker_id": "worker-example-001",
  "org_id": "workspace_example",
  "message": {
    "id": "msg_01JA",
    "status": "queued"
  },
  "chat": {
    "id": "chat_01J8",
    "status": "responding"
  },
  "ok": true
}

Authorization

Credential contract
{
  "type": "bearer",
  "scope": "messages:send",
  "transport": "Authorization: Bearer <workspace_api_key>"
}

Errors

StatusDescription
400The request body or parameters are invalid.
401The workspace API key is missing, invalid, expired, or revoked.
403The key lacks the required scope or its owner no longer has permission.
404The resource is missing or intentionally hidden by authorization.
429The key exceeded its current rate limit.

Usage notes