Utiliser le SDK

Les exemples suivants utilisent un client configuré selon le Démarrage rapide. Remplacez les ID par ceux de votre espace de travail.

Raccourcis de ressources

Les groupes suivants proposent des méthodes concises. Utilisez client.api pour les opérations absentes de ce tableau.

Groupe	Méthodes	Ressource
`client.assistants`	`list`, `create`, `get`, `update`, `delete`, `iterate`	Assistants
`client.calls`	`list`, `create`, `get`, `recording`, `iterate`	Appels et enregistrements
`client.campaigns`	`list`, `create`, `get`, `update`, `delete`, `start`, `stop`, `iterate`	Campagnes
`client.contacts`	`list`, `create`, `iterate`	Contacts de l’audience de l’espace de travail
`client.voices`	`list`, `preview`, `iterate`	Catalogue vocal et aperçus
`client.knowledgeBases`	`list`, `create`, `get`, `delete`, `iterate`	Bases de connaissances
`client.account`	`me`	Compte et espace de travail actuels

Les prospects propres à une campagne sont accessibles via client.api.listLeads, avec l’ID de campagne dans path.id, ou famulor list-leads <campaign-id> dans la CLI. client.contacts gère l’audience partagée de l’espace de travail.

Lire les réponses

Les méthodes de ressources conservent l’enveloppe de réponse de l’API : le résultat se trouve dans data, et les listes peuvent inclure meta.pagination.

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);

Utilisez le chaînage optionnel pour les métadonnées et les champs pouvant valoir null. Certains résultats, comme un résumé d’appel ou un enregistrement, ne sont disponibles qu’après traitement. Omettre un champ facultatif et envoyer null sont deux actions différentes ; envoyez null uniquement lorsque la Référence API l’autorise.

Charger les pages à la demande

Utilisez l’itérateur asynchrone pour les ressources paginées compatibles :

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

limit correspond à la taille d’une page, pas au nombre total d’éléments parcourus. L’itérateur conserve les filtres et avance le décalage jusqu’à la fin. Quitter la boucle arrête le chargement de nouvelles pages. La pagination par décalage n’est pas un instantané : des ajouts ou modifications simultanés peuvent changer le contenu des pages. Pour définir une limite de sécurité, passez par exemple { maxPages: 100 } comme deuxième argument. Atteindre cette limite avant la fin produit une erreur, sans renvoyer silencieusement un résultat partiel. Pour contrôler les pages manuellement, appelez client.calls.list() avec limit et offset, puis consultez meta.pagination. Les listes classiques renvoient 50 éléments par défaut et en acceptent jusqu’à 200 ; respectez les limites de chaque opération. La commande CLI équivalente est famulor list-calls --status completed --limit 50 ; ajoutez --all pour charger toutes les pages.

Utiliser toute opération de l’API publique

client.api expose les ID d’opération de la Référence API sous forme de méthodes typées. Les entrées sont regroupées dans path, query, body et headers au lieu de mélanger différents paramètres.

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);

Pour un appel sortant, la méthode API complète est :

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

console.log(result.data.id);

Le raccourci de ressource est client.calls.create(body). Les deux méthodes utilisent la même API et conservent les mêmes réponses et autorisations.

Méthode SDK	Opération REST	Commande CLI
`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>`

Utilisez l’autocomplétion de votre éditeur pour découvrir les méthodes. Consultez Outils MCP et portées pour utiliser les fonctions correspondantes dans un assistant IA.

Télécharger les réponses binaires

Les opérations audio renvoient un ArrayBuffer, sans enveloppe JSON data. Par exemple, téléchargez un aperçu Full Duplex existant au format WAV :

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));

Choisissez un ID de voix Full Duplex opaque dans le catalogue. Votre espace doit avoir accès au mode vocal correspondant. Un aperçu absent produit une erreur API ; cette requête ne crée pas de nouvel échantillon.

Téléverser des fichiers

Passez un corps FormData aux opérations acceptant les fichiers multipart. Le SDK définit le type de contenu multipart et sa délimitation :

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,
});

Les avatars acceptent PNG, JPEG ou WebP, avec une taille maximale de 1 Mo à l’envoi. Respectez les exigences de chaque opération. Les commandes CLI équivalentes pour ces deux exemples sont :

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

Adapter une requête

Les options de requête sont le dernier argument, après les paramètres de la méthode. Les méthodes générées de client.api reçoivent d’abord l’entrée groupée, puis les options. Les raccourcis de ressources ont des nombres d’arguments différents. Une liste reçoit par exemple la requête, puis les options :

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

Pour modifier un assistant, placez les options après l’ID et le corps ; pour télécharger de l’audio, après l’ID et la requête ; pour account.me(), comme seul argument. Une requête vide conserve les valeurs par défaut. Remplacez les ID avant l’exécution ; modifier un assistant change sa configuration.

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);

Voir Configuration et erreurs pour l’annulation, les classes d’erreur et les répétitions.

​Raccourcis de ressources

​Lire les réponses

​Charger les pages à la demande

​Utiliser toute opération de l’API publique

​Télécharger les réponses binaires

​Téléverser des fichiers

​Adapter une requête