API Reference›Messages›Send Message

Send Message

POST/v1/agents/:id/messagesproject:message

Request body

json
{
  "sessionId": "chat-session-1",
  "message": "Hello",
  "metadata": { "source": "web" },
  "executionPrincipal": { "type": "service" }
}

executionPrincipal (optional)

json
{ "type": "service" }

or

json
{ "type": "end_user", "endUserId": "user_123" }

If omitted:

  • Rooaak uses the agent default principal.
  • If the agent default principal is end_user, request must provide executionPrincipal.endUserId.

cURL

bash
curl -X POST "$ROOAAK_BASE_URL/v1/agents/$AGENT_ID/messages" \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-001" \
  -d '{"sessionId":"chat-session-1","message":"Hello","executionPrincipal":{"type":"service"}}'

Success responses

200

json
{
  "messageId": "uuid",
  "status": "responded",
  "response": "..."
}

202

json
{
  "messageId": "uuid",
  "status": "pending"
}

Behavior notes

  • Ensures agent belongs to current project.
  • Ensures runtime is running before insert.
  • Default sync wait timeout is 30s (ROOAAK_SYNC_MESSAGE_TIMEOUT_MS).
  • Poll interval for sync wait is 500ms.
  • On idempotency collision (23505), existing message is reused.
  • Message context persists both metadata and resolved executionPrincipal.

Common errors

  • 400 BAD_REQUEST: invalid executionPrincipal.
  • 400 BAD_REQUEST: executionPrincipal.endUserId is required when the agent default principal is end_user.