Getting Started

Build a real-time human-AI agent chat in under 5 minutes.

Time to complete: ~5 minutes

Step 1: Sign up

Create a free account at app.hi-loop.com. No credit card required. A space and API key are created automatically.

Step 2: Copy your API key

Go to Admin → API Key. Your API key starts with hlp_. Copy it — this is all you need.

Step 3: Install the SDK

npm install hiloop-sdk

Step 4: Send a message

Create a file called bot.mjs and paste this:

bot.mjs 
import { HiloopClient } from "hiloop-sdk";
import { randomUUID } from "crypto";

const client = new HiloopClient({
  apiKey: "hlp_YOUR_KEY_HERE",
  agentName: "my-first-bot",
});

const sessionId = randomUUID();
await client.sendConvSessionMessage(sessionId, "Hello from my bot!");
console.log("Message sent! Check the Hiloop app.");

Run it: 

node bot.mjs

Open app.hi-loop.com — you'll see my-first-bot with the message in your session list. The agent was created automatically.

Step 5: Real-time with WebSocket

For real-time two-way messaging, use the WebSocket client. Create bot-ws.mjs:

bot-ws.mjs 
import { HiloopWsClient } from "hiloop-sdk";
import { randomUUID } from "crypto";

const ws = new HiloopWsClient({
  apiKey: "hlp_YOUR_KEY_HERE",
  agentName: "support-bot",
});

// Receive messages from all sessions (auto-decrypted)
ws.on("session.message.new", (msg) => {
  console.log(`[${msg.agentName}] [${msg.sessionId}] ${msg.senderName}: "${msg.content}"`);
});

await ws.connect();

// Send a greeting — session is auto-created
const sessionId = randomUUID();
await ws.sendSessionMessage(sessionId, "Hey! How can I help you today?");
console.log("Waiting for replies... (Ctrl+C to quit)");

Run it: 

node bot-ws.mjs

Now open the session in the Hiloop app and type a reply. You'll see it appear in your terminal instantly — with typing indicators and read receipts.

Step 6: Send rich messages with components

Messages can include composable components — cards, diffs, metrics, buttons, and more. Create bot-rich.mjs:

bot-rich.mjs 
import { HiloopClient } from "hiloop-sdk";
import { approval, report } from "@hiloop/shared";
import { randomUUID } from "crypto";

const client = new HiloopClient({
  apiKey: "hlp_YOUR_KEY_HERE",
  agentName: "deploy-bot",
});

const sessionId = randomUUID();

// Plain message
await client.sendMessage(sessionId, "Build complete. Ready to deploy.");

// Approval with action buttons
await client.sendMessage(sessionId, "Deploy v2.0?", {
  components: approval("Deploy v2.0 to production?", ["Deploy", "Cancel"]),
  priority: "high",
});

// Report with metrics
await client.sendMessage(sessionId, "Monthly Report", {
  components: report("February Revenue", [
    { type: "metric_grid", data: { metrics: [
      { label: "Revenue", value: "$1.2M", change: "+12%" },
      { label: "Profit", value: "$310K", change: "+28%" },
    ]}},
  ]),
});

console.log("Rich messages sent! Check the Hiloop app.");

Run it: 

node bot-rich.mjs

Open the session in the Hiloop app — you'll see the message with interactive buttons, metrics, and more. All components are E2E encrypted.

What just happened

  • Agent auto-created — "support-bot" was provisioned from your API key and agent name. No manual setup.
  • Session auto-created — the session was created when you sent the first message. Just pass any UUID.
  • E2E encrypted — all messages are encrypted before leaving your process. The server never sees plaintext.
  • Real-time — the WebSocket delivers messages, typing indicators, and read receipts instantly.

What's next?