Chats API

Use client.chats when your agent or automation should open a chat for a human — for example a nightly cron that opens a review thread, or a parent agent spawning a child conversation.

Chats are separate from one-off sendToHuman tasks: a chat is a long-lived Eve session with a transcript, a single owner, and a deep link into the inbox.

Client setup

Use the same createClient module as tasks. Authenticate with your workspace API key (ll_* from Settings → API Keys).

// lib/robotrock.ts
import { createClient } from "robotrock";

export const robotrock = createClient({
  app: "my-agent",
});

ROBOTROCK_API_KEY=ll_your_api_key_here

Create a chat

import { robotrock } from "@/lib/robotrock";

const { tenantSlug, chats } = await robotrock.chats.create({
  agentIdentifier: "support-agent",
  title: "Review overnight escalations",
  ownerEmail: "alex@example.com",
  messages: [
    {
      role: "assistant",
      content: "Three tickets need your review from last night.",
    },
  ],
});

const chat = chats[0];
console.log(chat.deepLink); // open in RobotRock inbox
console.log(chat.chatId);

Field	Required	Description
`agentIdentifier`	Yes*	Eve agent slug (`agentIdentifier` on the deployment)
`parentChatId`	Yes*	Spawn from an existing chat (inherits agent, connection, owner)
`title`	Yes	Shown in the conversation list
`ownerEmail`	Yes**	Email of the user who owns the chat in the inbox
`app`	No	Inbox app bucket (defaults to client `app`)
`connectionId`	No	Specific Eve connection when a tenant has several
`messages`	No	Seed transcript (defaults to the agent welcome message)
`source`	No	Provenance label for audit (`"api"`, `"cron"`, `"agent"`, …)

* Provide either agentIdentifier or parentChatId.

** Required when parentChatId is not set. Child chats inherit the parent owner.

The response includes deepLink — a path under your tenant inbox with agent and session query params.

Close a chat

When the agent is done, archive the session:

await robotrock.chats.close(chat.chatId, {
  reason: "All items reviewed",
});

Eve HITL audit helpers

For custom Eve hooks that run outside the dashboard UI, the chats namespace also supports:

Method	Purpose
`stageHitlRequests`	Persist pending Eve HITL requests on the chat for durable audit
`getStagedHitlRequests`	Read staged requests by `eveSessionId`
`logInputSubmission`	Record an Eve HITL choice on the audit trail
`linkTask`	Associate an inbox task with the originating Eve session

These mirror the POST /v1/agent-chats/* routes on the RobotRock API. Most Eve agents use the built-in RobotRock integration instead of calling these directly.

HTTP endpoints

Method	Path	Description
`POST`	`/v1/agent-chats`	Create a chat owned by a user
`POST`	`/v1/agent-chats/:chatId/close`	Archive a chat
`POST`	`/v1/agent-chats/stage-hitl`	Stage Eve HITL requests
`GET`	`/v1/agent-chats/staged-hitl`	List staged HITL requests
`POST`	`/v1/agent-chats/audit-input`	Log HITL input submission
`POST`	`/v1/agent-chats/link-task`	Link inbox task to Eve session

All routes require the same API key auth as task creation. Rate limits and daily usage match the task API.

Overview — inbox UI and delegation from chat
Build agents — Eve agent that receives these chats
Send to human — one-off inbox tasks (not chat sessions)