Getting Started›Quickstart

Quickstart

Last updated 2026-02-13

Rooaak Cloud is designed so you can go from "API key" to "agent replies to my app" in a few minutes.

This page shows the fastest end-to-end path:

  1. Install the SDK.
  2. Create an agent.
  3. Force-start the runtime (optional).
  4. Send a message and handle async fallback (pending).

If you prefer to use curl, see /docs/getting-started/send-your-first-message.

1. Install the TypeScript SDK

bash
npm install rooaak

2. Set env vars

Required:

  • ROOAAK_API_KEY (example prefix: rk_live_...)

Optional:

  • ROOAAK_BASE_URL (defaults to https://www.rooaak.com)

3. Initialize client

typescript
import { RooaakClient } from "rooaak";

const rooaak = new RooaakClient({
  apiKey: process.env.ROOAAK_API_KEY!,
  baseUrl: process.env.ROOAAK_BASE_URL, // optional
  timeout: 180_000, // recommended for first runs (cold start)
});

4. Create an agent

typescript
const agent = await rooaak.agents.create({
  name: "Support Assistant",
  externalId: "customer-user-123",
  avatarUrl: "https://api.dicebear.com/9.x/bottts/svg?seed=support-assistant",
  personality: "Helpful, concise, accurate",
  contextUrl: "https://your-app.com/api/agent-context/customer-user-123",
  alwaysOn: false,
});

Notes:

  • name is required.
  • contextUrl is optional. If set, Rooaak will fetch it from your server and pass it into the runtime as dynamic context.

5. Optional: start the agent runtime

You do not have to call start explicitly. Sending a message will auto-provision the runtime as needed.

However, agents.start(...) is useful when you want to avoid first-message cold start latency.

typescript
await rooaak.agents.start(agent.id);

6. Send a message

typescript
const result = await rooaak.messages.send(
  {
    agentId: agent.id,
    sessionId: "chat-session-1",
    message: "What is your refund policy?",
  },
  `msg-${Date.now()}` // Idempotency-Key (recommended if you retry)
);

if (result.status === "responded") {
  console.log(result.response);
}

7. Handle async fallback (pending)

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

8. Optional: register webhooks (recommended in production)

typescript
const webhook = await rooaak.webhooks.create({
  url: "https://your-app.com/webhooks/rooaak",
  events: ["message.responded", "agent.error"],
});

// Persist webhook.secret securely; returned only once
console.log(webhook.secret);

9. Copy-paste E2E script (Node.js)

If you want a single copy-paste smoke test you can run in a fresh folder:

bash
mkdir -p /tmp/rooaak-e2e && cd /tmp/rooaak-e2e
npm init -y
npm i rooaak

export ROOAAK_API_KEY="rk_live_..."
node e2e.mjs
javascript
// e2e.mjs
import { RooaakClient } from "rooaak";

const apiKey = process.env.ROOAAK_API_KEY;
if (!apiKey) throw new Error("Missing ROOAAK_API_KEY");

const rooaak = new RooaakClient({
  apiKey,
  baseUrl: "https://www.rooaak.com",
  timeout: 180_000,
});

const runId = new Date().toISOString().replace(/[:.]/g, "-");

const agent = await rooaak.agents.create({
  name: `sdk-e2e-${runId}`,
  avatarUrl: `https://api.dicebear.com/9.x/bottts/svg?seed=${encodeURIComponent(runId)}`,
  personality: "E2E test agent. Reply with exactly what is requested.",
  alwaysOn: false,
});

console.log("agent", { id: agent.id, status: agent.status });

await rooaak.agents.start(agent.id); // optional: warms runtime

const sessionId = `e2e-${Math.random().toString(16).slice(2)}`;
const idempotencyKey = `e2e-${Date.now()}-${Math.random().toString(16).slice(2)}`;

const send = await rooaak.messages.send(
  { agentId: agent.id, sessionId, message: "Reply with exactly: pong" },
  idempotencyKey
);

const final =
  send.status === "responded"
    ? { status: "responded", response: send.response }
    : await rooaak.messages.waitForResponse(send.messageId, {
        timeoutMs: 180_000,
        pollIntervalMs: 2_000,
      });

console.log("final", { status: final.status, response: final.response });

10. Optional: start from official starter repos

  • Custom app UI: rooaak-custom-ui-sample-app
  • Slack adapter: rooaak-slack-adapter-starter
  • WhatsApp Cloud adapter: rooaak-whatsapp-cloud-adapter-starter