SDK TypeScript

Le paquet allomi est un petit client TypeScript de l'API REST. Il n'a aucune dépendance, utilise le fetch global (Node 22+, Bun, Deno, navigateurs, runtimes edge) et ses types viennent des mêmes contrats que l'API.

Installation

npm install allomi

Créer le client

import { Allomi } from "allomi";

const allomi = new Allomi({
  apiKey: process.env.ALLOMI_API_KEY, // par défaut : la variable ALLOMI_API_KEY
  // baseUrl: "http://localhost:3001", // par défaut : ALLOMI_BASE_URL, puis https://api.allomi.ai
});

Garde la clé côté serveur. Ne la livre jamais à un navigateur.

Appels

const call = await allomi.calls.create({
  to: "+33199000001", // ou contactId
  prompt: "Demande si le colis est arrivé, sinon quand il arrivera.",
  language: "fr",
  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: "Demande aussi un numéro de suivi.", interrupt: false });
await allomi.calls.hangUp(call.id);

say donne une consigne à l'assistant pendant l'appel. hangUp y met fin.

Questions (asks)

Un « ask » appelle une personne, lui lit une question, recueille la réponse et te la renvoie. C'est ce qu'utilisent les agents pour obtenir une décision humaine.

const ask = await allomi.asks.create({
  target: "owner", // ou { target: "contact", contactId }
  question: "Je peux fusionner la branche de release maintenant ?",
  context: "La CI est verte.",
  expiresInMinutes: 30,
});
const answer = await allomi.asks.get(ask.id);

Erreurs

Une requête en échec lève une AllomiError avec le status HTTP, le type et le code de l'erreur, le param le cas échéant et le requestId.

import { Allomi, AllomiError } from "allomi";

try {
  await allomi.calls.create({ to: "+33199000001", prompt: "Bonjour" });
} catch (e) {
  if (e instanceof AllomiError && e.code === "quota_exceeded") {
    // le budget de minutes est épuisé : propose de changer d'offre
  } else throw e;
}

Idempotence

Passe une clé d'idempotence pour rendre une création rejouable sans risque :

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

Autres endpoints

allomi.request(method, path, { body, query }) appelle n'importe quel endpoint de la référence de l'API, avec la même authentification et la même gestion d'erreurs.