API Reference

Everything a bot can do to Atlas, programmatically. Every function exists on the bot (bot.sendText(chatId, …)) and, bound to the current chat, on the handler context (ctx.sendText(…)). The SDK ships full TypeScript types for all of it.

Build native screens with the SDK UI libraries, then open pages or bottom sheets using existing chat buttons. The guides include import paths, types, and a complete food-ordering example.

Messaging

Choice buttons

Tappable chips under the bot's message — Atlas's inline keyboard. Tapping sends the option's value back as an ordinary reply, so your receive path is one code path for taps and typing. Older app versions render a numbered list instead; nothing breaks.

await ctx.sendChoices("Which time works best?", ["Morning", "Afternoon"]);

// Label and value can differ — labels for humans, values for your router:
await ctx.sendChoices("New case T001", [
    { label: "Claim", value: "/claim T001" },
    { label: "Pass",  value: "/pass T001" }
]);

// On the way back in:
bot.onMessage((ctx) => {
    ctx.body;    // "/claim T001" — the tapped value (or whatever was typed)
    ctx.choice;  // "/claim T001" when the app marked it as a tap, else null
});

// LIVE messages: hold the event id, edit the bubble in place later —
// freeze the buttons once the moment passes (claimed, passed, canceled).
const sent = await ctx.sendChoices("New case T001", [
    { label: "Claim", value: "/claim T001" },
    { label: "Pass",  value: "/pass T001" }
]);
await bot.editMessage(chatId, sent.eventId, "New case T001 — taken by Dr. Chen", {
    choices: [
        { label: "Claim", value: "/claim T001", disabled: true },
        { label: "Pass",  value: "/pass T001",  disabled: true }
    ],
    disabled: true    // the whole widget freezes; chips stay visible as a record
});

Disabled works at both levels: per option ({label, value, disabled: true}) and whole-widget (disabled: true on the edit). Frozen chips render dimmed and stop responding — on every member's device. Doctor Finder uses this everywhere: the losers' dispatches gray out with "Taken by Dr. Chen", a pass freezes your own, a patient cancel grays out all of them.

Grids and silent buttons

// Nested arrays = a grid, one inner array per row (max 4 rows).
// silent: true = the tap fires an INVISIBLE callback — nothing posts to
// the chat; your handler gets ctx.isCallback and answers by EDITING the
// menu message in place.
const menu = await ctx.sendChoices("Coffee menu — page 1", [
    ["Espresso", "Latte", "Cortado"],
    [{ label: "Next page ▸", value: "/page 2", silent: true }]
]);

bot.onCommand("page", async (ctx) => {
    if (!ctx.isCallback) return;
    await ctx.editMessage(menu.eventId, "Coffee menu — page 2", {
        choices: [
            ["Flat white", "Mocha", "Drip"],
            [{ label: "◂ Back", value: "/page 1", silent: true }]
        ]
    });
});

Reply keyboards

The other keyboard flavor: preset answers rendered as a strip above the user's input bar, not under a message. It stays until used (oneTime), removed by the bot, or dismissed by the user; taps post visible replies.

await ctx.sendKeyboard("How was your visit?", ["Great", "Okay", "Bad"], { oneTime: true });
// later, to clear a persistent keyboard:
await ctx.removeKeyboard("Thanks for the feedback!");

Media — every medium, both directions

Inbound media arrives on the same handler as text:

bot.onMessage(async (ctx) => {
    if (!ctx.attachment) return;
    const { type, filename, mimetype, size } = ctx.attachment;
    // type: "photo" | "video" | "voiceNote" | "document" | "contact" | "location"
    const { bytes } = await ctx.attachment.download();
});

Read state

Chats & members

Calls

Bot chats are text-only — no call button, by design. When a conversation needs voice, createGroup the humans together: a group is a normal chat and its call button just works. No flags, no permissions, no special cases.

Push notifications

Atlas app commands

A bot can ask the user's Atlas to do something on its behalf — the same tool surface Atlas's own on-device agent drives. Commands ride the chat and execute on the user's device behind a hard curated catalog (below) with per-command argument sanitizers — spoof-guarded to the chat's bot peer, deduped on retry, and every outcome echoed back to the bot as a result event. Anything off-catalog is dropped, not queued.

const app = bot.app(chatId);              // or ctx.app inside a handler

// Reads return their payload in reply.result.result:
const contact = await app.lookupContact("Mario");
console.log(contact.result?.result);      // "Mario Rossi — +1 555 0100 …"
const inbox = await app.listMessages({ chat: "Maya", count: 10 });

// Writes report ok/failure; creates hand back the new item's id:
await app.sendAsUser("On my way!", "Maya");
const bucket = await app.createBucket("Appointments");
await app.renameBucket(bucket.result?.createdId, "Dermatology");

// Calls, device routes, notifications:
await app.startCall("voice", "Maya");
await app.composeSms("+1 555 0100", "Running late");
await app.scheduleNotification({ title: "Meds", body: "3pm dose", date: "2026-07-09 15:00", id: "meds" });

// General forms: runCommand waits for the echo, sendCommand doesn't.
const reply = await bot.runCommand(chatId, "search.messages", { query: "insurance" }, { timeoutMs: 20_000 });
await bot.sendCommand(chatId, "action.create", { title: "Follow up with Dr. Chen" });

The return value

Every app.* method and runCommand return Promise<CommandReply>; sendCommand returns Promise<SendResult> (no waiting):

interface CommandReply {
    sent: boolean;            // false = blocked by the outbound guards
    reason?: string;          //   why (cooldown, consecutive cap, …)
    commandId?: string;       // the command's id — the echoed result carries the same one
    result?: CommandResult;   // undefined = timed out waiting for the device
}

interface CommandResult {
    id: string;               // matches commandId
    command: string;          // the command this answers
    ok: boolean;              // the executor ran (see note below)
    result: string | null;    // the payload: list text, lookup text, confirmation, …
    createdId: string | null; // new item's id — createAction and createBucket only
}

ok means the command reached its executor and ran: for device-route and create/delete commands a false is a real failure (with result saying why). Agent-tool commands (marked agent tool below) always execute and report their outcome — including "couldn't find that" — as prose in result, so read the text, not just the flag. A result of undefined on the reply means the wait timed out (default 20s) — the user's device is offline or hasn't synced yet, not a failure; a deduped retry also stays silent.

General forms

The catalog

All methods below return Promise<CommandReply>. agent tool = executed by the on-device agent's own executor; the payload comes back as prose in result.result.

Params are sanitized on-device per command (unknown keys stripped, identifiers namespaced, fixed values forced — a bot's confirm never passes), and commands execute through the same gated tool registry that powers Atlas's own agent and Experiences. Deliberately off-catalog: bulk wipes (wipe_all, delete-all), the user's profile/custom instructions, Atlas toggling, experience install, and anything needing a typed user confirmation.

The platform LLM

Guards & state

Advanced: the raw client

Everything above is guard-gated sugar over bot.client — the low-level chat API, there when you outgrow the sugar. The Doctor Finder uses it to create its case groups. No guards apply at this layer; you're on your own recognizance.