SDK-Schnellstart

Diese Anleitung beginnt mit einer Leseanfrage. Sobald die Verbindung funktioniert, können Sie mit einem separaten Skript einen ausgehenden Anruf starten.

Paket installieren

Führen Sie in Ihrem Serverprojekt Folgendes aus:

npm install famulor-sdk

Verwenden Sie Node.js 22 oder neuer. Das Paket unterstützt TypeScript und JavaScript sowie ESM import und CommonJS require.

Workspace-API-Schlüssel erstellen

Wählen Sie in Famulor den gewünschten Workspace aus, öffnen Sie Einstellungen → API & MCP und erstellen Sie einen Schlüssel. Kopieren Sie den vollständigen Wert, solange er sichtbar ist; er wird nur einmal angezeigt.Der Workspace benötigt API-Zugriff über seinen Tarif oder ein Add-on. Ein im Dashboard erstellter Schlüssel besitzt alle Scopes. Für eingeschränkte Berechtigungen lesen Sie Sicherer Umgang mit API-Schlüsseln.

Schlüssel auf dem Server speichern

Hinterlegen Sie den Schlüssel für die lokale Entwicklung in einer .env-Datei:

FAMULOR_API_KEY=fam_your_workspace_key

Nehmen Sie .env in .gitignore auf. Für gehostete Anwendungen verwenden Sie den Secret-Manager oder die Server-Umgebungseinstellungen Ihres Hosts. Das SDK erhält den Schlüssel ausdrücklich; es lädt keine .env-Dateien und wählt keinen Workspace automatisch aus.

Assistenten lesen

Speichern Sie diese Datei als sdk-read.mjs:

sdk-read.mjs

import { Famulor } from 'famulor-sdk';

if (!process.env.FAMULOR_API_KEY) {
  throw new Error('Set FAMULOR_API_KEY before running this script.');
}

const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });
const { data } = await client.assistants.list({ limit: 10 });

for (const assistant of data) {
  console.log(assistant.id, assistant.name);
}

Starten Sie das Skript mit Nodes Unterstützung für Umgebungsdateien:

node --env-file=.env sdk-read.mjs

Eine leere Liste bedeutet eine erfolgreiche Verbindung, wenn Ihr Workspace noch keine Assistenten enthält. Bei einem Fehler lesen Sie Fehlerbehebung.

Einen ausgehenden Anruf starten

Wählen Sie einen aktiven Assistenten mit einer zugewiesenen Rufnummer für ausgehende Anrufe. Verwenden Sie ein Ziel, das Sie anrufen möchten, im E.164-Format, beispielsweise +4915123456789.

Das nächste Skript startet einen echten ausgehenden Anruf und kann Workspace-Credits verbrauchen. Ersetzen Sie beide Befehlsargumente durch Ihre Assistenten-ID und das gewünschte Anrufziel.

Speichern Sie diese Datei als sdk-call.mjs:

sdk-call.mjs

import { Famulor } from 'famulor-sdk';

if (!process.env.FAMULOR_API_KEY) {
  throw new Error('Set FAMULOR_API_KEY before running this script.');
}

const [assistantId, toNumber] = process.argv.slice(2);
if (!assistantId || !toNumber) {
  throw new Error('Usage: node sdk-call.mjs <assistant-id> <E.164-number>');
}

const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });
const { data: call } = await client.calls.create({
  assistant_id: assistantId,
  to_number: toNumber,
});

console.log({ id: call.id, status: call.status });

node --env-file=.env sdk-call.mjs <assistant-id> <E.164-number>

Die Antwort enthält die ID und den anfänglichen Status des erstellten Anrufs. Eine erfolgreiche Erstellung bedeutet noch nicht, dass der Empfänger geantwortet hat. Speichern Sie die ID und lesen Sie das Ergebnis später:

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

Nutzen Sie bevorzugt den Webhook Ihres Assistenten für beendete Gespräche, um das endgültige Ergebnis zu erhalten; siehe Webhooks. Die entsprechenden CLI-Befehle lauten:

famulor create-call --assistant-id <assistant-id> --to-number <E.164-number>
famulor get-call <call-id>

Eigene Domain verwenden

Verwenden Sie für einen Whitelabel-Workspace die Domain Ihrer Anmeldung und ergänzen Sie /api/v1:

import { Famulor } from 'famulor-sdk';

const client = new Famulor({
  apiKey: process.env.FAMULOR_API_KEY,
  baseUrl: 'https://app.example.com/api/v1',
});

Jeder API-Schlüssel gehört zu genau einem Workspace. Verwenden Sie je Workspace einen eigenen Schlüssel und Client. Eine eigene Domain erweitert keine Berechtigungen und ändert keine API-Pfade. Unter SDK verwenden finden Sie Paginierung und vollständigen API-Zugriff. Konfiguration und Fehler erklärt die zuverlässige Behandlung von Anfragen.

​Einen ausgehenden Anruf starten

​Eigene Domain verwenden

Einen ausgehenden Anruf starten

Eigene Domain verwenden