SDK verwenden - Famulor

Die folgenden Beispiele verwenden einen konfigurierten client aus dem Schnellstart. Ersetzen Sie Ressourcen-IDs durch IDs aus Ihrem Workspace.

Ressourcen-Kurzmethoden

Die folgenden Gruppen bieten kurze Methoden. Verwenden Sie client.api für hier nicht aufgeführte Operationen.

Gruppe	Methoden	Ressource
`client.assistants`	`list`, `create`, `get`, `update`, `delete`, `iterate`	Assistenten
`client.calls`	`list`, `create`, `get`, `recording`, `iterate`	Anrufe und Aufnahmen
`client.campaigns`	`list`, `create`, `get`, `update`, `delete`, `start`, `stop`, `iterate`	Kampagnen
`client.contacts`	`list`, `create`, `iterate`	Kontakte in der Workspace-Zielgruppe
`client.voices`	`list`, `preview`, `iterate`	Stimmenkatalog und Vorschauen
`client.knowledgeBases`	`list`, `create`, `get`, `delete`, `iterate`	Wissensdatenbanken
`client.account`	`me`	Aktueller Account und Workspace

Kampagnenspezifische Leads erhalten Sie über client.api.listLeads mit der Kampagnen-ID in path.id oder über famulor list-leads <campaign-id> in der CLI. client.contacts verwaltet die gemeinsame Workspace-Zielgruppe.

Antworten lesen

Ressourcenmethoden behalten die API-Antwortstruktur bei: Das Ergebnis steht in data, und Listen können meta.pagination enthalten.

const response = await client.calls.list({
  status: 'completed',
  limit: 20,
  offset: 0,
});

console.log(response.data);
console.log(response.meta?.pagination);

const { data: call } = await client.calls.get('call-id');
console.log(call.status, call.summary);

Verwenden Sie Optional Chaining für Metadaten und Antwortfelder, die null sein können. Einige Ergebnisse, etwa eine Anrufzusammenfassung oder Aufnahme, sind erst nach der Verarbeitung verfügbar. Ein optionales Anfragefeld wegzulassen und null zu senden sind unterschiedliche Aktionen; senden Sie null nur, wenn die API-Referenz dies erlaubt.

Seiten nach Bedarf laden

Verwenden Sie für unterstützte paginierte Ressourcen den asynchronen Iterator:

for await (const call of client.calls.iterate({
  status: 'completed',
  limit: 50,
})) {
  console.log(call.id, call.status);
}

limit ist die Seitengröße und begrenzt nicht die Gesamtzahl der gelieferten Einträge. Der Iterator behält Ihre Filter bei und erhöht den Offset bis zum Ende der Liste. Wenn Sie die Schleife abbrechen, werden keine weiteren Seiten geladen. Offset-Paginierung ist keine Momentaufnahme: Gleichzeitige Einfügungen oder Änderungen können die Seiteninhalte verändern. Für eine Sicherheitsgrenze übergeben Sie beispielsweise { maxPages: 100 } als zweites Argument. Wird die Grenze vor Listenende erreicht, entsteht ein Fehler statt eines stillschweigend unvollständigen Ergebnisses. Für manuelle Seitensteuerung rufen Sie client.calls.list() mit limit und offset auf und prüfen anschließend meta.pagination. Übliche Listen-Endpunkte liefern standardmäßig 50 Einträge und erlauben bis zu 200; beachten Sie die Limits jedes Endpunkts. Der entsprechende CLI-Befehl lautet famulor list-calls --status completed --limit 50; mit --all laden Sie alle Seiten.

Jede öffentliche API-Operation verwenden

client.api stellt die Operation-IDs aus der API-Referenz als typisierte Methoden bereit. Eingaben werden in path, query, body und headers gruppiert, statt verschiedene Parameter zusammenzuführen.

const { data: account } = await client.api.getMe();

const { data: calls } = await client.api.listCalls({
  query: { status: 'completed', limit: 10 },
});

const { data: call } = await client.api.getCall({
  path: { id: 'call-id' },
});

console.log(account, calls.length, call.status);

Für einen ausgehenden Anruf lautet die vollständige API-Methode:

const result = await client.api.createCall({
  body: {
    assistant_id: '11111111-1111-4111-8111-111111111111',
    to_number: '+4915123456789',
  },
});

console.log(result.data.id);

Die kürzere Ressourcenmethode ist client.calls.create(body). Beide Methoden verwenden dieselbe API und behalten Antwortstruktur und Berechtigungen bei.

SDK-Methode	REST-Operation	CLI-Befehl
`client.api.getMe()`	`GET /api/v1/me`	`famulor get-me`
`client.api.listCalls()`	`GET /api/v1/calls`	`famulor list-calls`
`client.api.getCall()`	`GET /api/v1/calls/{id}`	`famulor get-call <id>`
`client.api.createCall()`	`POST /api/v1/calls`	`famulor create-call --assistant-id <id> --to-number <number>`

Nutzen Sie die Autovervollständigung Ihres Editors für alle Methoden. Unter MCP-Werkzeuge und Scopes erfahren Sie, wie Sie die entsprechenden Funktionen in einem KI-Assistenten verwenden.

Binäre Antworten herunterladen

Audio-Endpunkte geben einen ArrayBuffer ohne JSON-Wrapper data zurück. Laden Sie beispielsweise eine vorhandene Full-Duplex-Stimmenvorschau als WAV-Audio herunter:

import { writeFile } from 'node:fs/promises';

const preview = await client.api.getVoicePreview({
  path: { id: 'voice-id' },
  query: { realtime_variant: 'full_duplex' },
});

await writeFile('preview.wav', new Uint8Array(preview));

Wählen Sie eine unverändert übernommene Full-Duplex-Stimmen-ID aus dem Stimmenkatalog. Ihr Workspace benötigt Zugriff auf diesen Stimmenmodus. Eine fehlende Vorschau führt zu einem API-Fehler; diese Anfrage erzeugt kein neues Beispiel.

Dateien hochladen

Übergeben Sie bei Operationen mit Multipart-Uploads einen FormData-Body. Das SDK setzt den Multipart-Content-Type einschließlich Boundary:

import { readFile } from 'node:fs/promises';

const file = await readFile('avatar.png');
const form = new FormData();
form.set('file', new Blob([new Uint8Array(file)], { type: 'image/png' }), 'avatar.png');

await client.api.setAssistantAvatar({
  path: { id: 'assistant-id' },
  body: form,
});

Avatar-Uploads akzeptieren PNG, JPEG oder WebP mit maximal 1 MB eingehender Dateigröße. Beachten Sie die Dateivorgaben jeder Operation. Die entsprechenden CLI-Befehle für beide Beispiele lauten:

famulor get-voice-preview <voice-id> --realtime-variant full_duplex --output-file preview.wav
famulor set-assistant-avatar <assistant-id> --file avatar.png

Eine einzelne Anfrage anpassen

Anfrageoptionen stehen als letztes Argument nach den Eingabeparametern der Methode. Generierte client.api-Methoden erhalten zuerst die gruppierte Eingabe und dann die Anfrageoptionen. Ressourcen-Kurzmethoden haben unterschiedliche Argumentzahlen. Eine Liste erhält beispielsweise zuerst die Abfrage und dann die Optionen:

const response = await client.assistants.list(
  { limit: 10 },
  { timeoutMs: 10_000, maxRetries: 0 },
);

Bei einer Assistentenänderung stehen die Optionen nach ID und Body, beim Audio-Download nach ID und Abfrage und bei account.me() als einziges Argument. Mit einer leeren Abfrage behalten Sie die Standardwerte bei. Ersetzen Sie vor dem Ausführen die Ressourcen-IDs; eine Assistentenänderung verändert dessen Konfiguration.

const controller = new AbortController();
const options = { signal: controller.signal, timeoutMs: 10_000, maxRetries: 0 };

await client.assistants.update('assistant-id', { name: 'Support' }, options);
const recording = await client.calls.recording('call-id', {}, options);
const preview = await client.voices.preview('voice-id', {}, options);
const account = await client.account.me(options);

await client.api.getMe(undefined, options);

Konfiguration und Fehler erklärt Abbruch, Fehlerklassen und Wiederholungsverhalten.

​Ressourcen-Kurzmethoden

​Antworten lesen

​Seiten nach Bedarf laden

​Jede öffentliche API-Operation verwenden

​Binäre Antworten herunterladen

​Dateien hochladen

​Eine einzelne Anfrage anpassen