TypeScript SDK

The allomi package is a small TypeScript client for the REST API. It has no runtime dependency, uses the global fetch (Node 22+, Bun, Deno, browsers, edge runtimes) and ships its types from the same contracts as the API.

Install

npm install allomi

Create the client

import { Allomi } from "allomi";

const allomi = new Allomi({
  apiKey: process.env.ALLOMI_API_KEY, // default: the ALLOMI_API_KEY variable
  // baseUrl: "http://localhost:3001", // default: ALLOMI_BASE_URL, then https://api.allomi.ai
});

Keep the key on a server. Never ship it to a browser.

Calls

const call = await allomi.calls.create({
  to: "+33199000001", // or contactId
  prompt: "Ask if the parcel arrived, and if not, when it will.",
  language: "en",
  voice: "brise",
  maxMinutes: 5,
  webhookUrl: "https://example.com/hooks/allomi",
});

const same = await allomi.calls.get(call.id);
const page = await allomi.calls.list({ limit: 20 });
await allomi.calls.say(call.id, { text: "Please also ask for a tracking number.", interrupt: false });
await allomi.calls.hangUp(call.id);

say gives the assistant an instruction while the call is running. hangUp ends it.

Asks

An ask calls a human, reads a question, collects the answer and returns it. It is what agents use to get a decision from a person.

const ask = await allomi.asks.create({
  target: "owner", // or { target: "contact", contactId }
  question: "Can I merge the release branch now?",
  context: "The CI is green.",
  expiresInMinutes: 30,
});
const answer = await allomi.asks.get(ask.id);

Errors

Failed requests throw an AllomiError with the HTTP status, the error type and code, the param when relevant and the requestId.

import { Allomi, AllomiError } from "allomi";

try {
  await allomi.calls.create({ to: "+33199000001", prompt: "Hello" });
} catch (e) {
  if (e instanceof AllomiError && e.code === "quota_exceeded") {
    // the minute budget is exhausted: show an upgrade link
  } else throw e;
}

Idempotency

Pass an idempotency key to make a creation safe to retry:

await allomi.calls.create(body, { idempotencyKey: crypto.randomUUID() });

Other endpoints

allomi.request(method, path, { body, query }) calls any endpoint of the API reference with the same authentication and error handling.