Getting Started›Send Your First Message

Send Your First Message

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

Last updated 2026-02-13

This endpoint is the primary "talk to my agent" call.

It can complete synchronously (responded) or fall back to async (pending) depending on runtime availability and load.

Request

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": "Can you summarize our plan?",
    "metadata": { "channel": "web" }
  }'

Synchronous success (`200`)

If runtime responds before timeout:

json

{
  "messageId": "uuid",
  "status": "responded",
  "response": "Here is a summary..."
}

Async fallback (`202`)

If no response before timeout:

json

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

Important behavior

Default sync wait is 30 seconds (ROOAAK_SYNC_MESSAGE_TIMEOUT_MS override).
Polling interval for sync wait is 500ms.
If idempotency insert collides (unique violation), Rooaak returns existing message for that project/idempotency pair.
Endpoint always verifies agent belongs to authenticated project.

SDK version (TypeScript)

typescript

import { RooaakClient } from "rooaak";

const rooaak = new RooaakClient({
  apiKey: process.env.ROOAAK_API_KEY!,
  timeout: 180_000,
});

const sent = await rooaak.messages.send(
  { agentId: process.env.AGENT_ID!, sessionId: "chat-1", message: "Reply with exactly: pong" },
  `idem-${Date.now()}`
);

if (sent.status === "responded") {
  console.log(sent.response);
} else {
  const final = await rooaak.messages.waitForResponse(sent.messageId, { timeoutMs: 180_000, pollIntervalMs: 2_000 });
  console.log(final.response);
}